Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 05. 20:56

AgentGuardian 구축하기: 에이전트형 AI 워크플로우를 위한 로컬 우선 보안 스캐너

요약

AgentGuardian은 AI 에이전트 워크플로우의 보안 위험을 평가하기 위해 구축된 로컬 우선 보안 스캐너입니다. 프롬프트 인젝션, 도구 오용, 데이터 노출 등의 위험을 로컬 LLM과 규칙 기반 엔진을 통해 분석합니다.

핵심 포인트

  • 로컬 LLM과 Ollama를 사용하여 외부 API 키 없이 보안 스캔 가능
  • 프롬프트 인젝션 및 도구 오용 등 주요 AI 보안 위험 탐지
  • 에이전트의 도구 접근 권한과 자율성에 따른 위험 점수 산출
  • Python, Streamlit 기반의 실용적인 보안 프로토타입 구축

AI 에이전트(AI agents)는 단순한 채팅 인터페이스에서 도구를 사용하고, 데이터에 접근하며, 워크플로우를 트리거하고, 메시지를 작성하며, 때로는 사용자를 대신하여 행동을 취할 수 있는 시스템으로 빠르게 진화하고 있습니다. 이러한 변화는 흥미롭지만, 동시에 심각한 보안 문제를 야기합니다:

AI 에이전트를 배포하기 전에 어떻게 그 위험을 평가할 것인가?

이 질문이 저로 하여금 _AgentGuardian_을 구축하게 만들었습니다. AgentGuardian은 프롬프트 인젝션 (prompt injection), 도구 오용 (tool misuse), 과도한 자율성 (excessive autonomy), 민감한 데이터 노출 (sensitive data exposure), 안전하지 않은 출력 처리 (insecure output handling), 그리고 인간의 감독 부족 (lack of human oversight)과 같은 위험을 에이전트형 AI 워크플로우에서 스캔하는 로컬 우선 (local-first) AI 보안 웹 앱입니다.

목표는 다음을 사용하여 실용적인 프로토타입을 구축하는 것이었습니다:

  • Python
  • Streamlit
  • Pandas
  • Ollama
  • 로컬 LLM (A local LLM)
  • 결정론적 규칙 기반 위험 점수 엔진 (A deterministic rule-based risk scoring engine)

외부 LLM API 키는 필요하지 않습니다.

AgentGuardian을 구축한 이유

AI 에이전트의 능력이 향상됨에 따라, 다음과 같은 도구들과 점점 더 많이 연결되고 있습니다:

  • 이메일 (Email)
  • 파일 (Files)
  • 데이터베이스 (Databases)
  • CRM
  • 티켓팅 시스템 (Ticketing systems)
  • 캘린더 (Calendars)
  • 결제 시스템 (Payment systems)
  • 웹 브라우저 (Web browsers)

이러한 도구들은 에이전트를 더 유용하게 만들지만, 동시에 위험도 증가시킵니다.

예를 들어, 공개 문서를 요약하기만 하는 AI 어시스턴트의 위험 프로필 (risk profile)은 고객 불만 사항을 읽고, 주문 내역을 확인하며, 환불 응답 초안을 작성하고, 고객에게 이메일을 보내는 AI 에이전트의 위험 프로필과 매우 다릅니다.

두 번째 에이전트는 민감한 데이터, 외부 입력, 그리고 비즈니스에 영향을 미치는 도구에 접근할 수 있습니다. 이는 배포 전에 더 강력한 보안 검토가 필요함을 의미합니다.

저는 AgentGuardian이 다음과 같은 질문에 답하는 데 도움이 되기를 원했습니다:

  • 이 에이전트는 어떤 도구에 접근할 수 있는가?
  • 어떤 유형의 데이터를 처리하는가?
  • 신뢰할 수 없는 외부 입력을 받는가?
  • 자동으로 행동을 취할 수 있는가?
  • 인간의 승인이 필요한가?
  • 팀이 배포 전에 수정해야 할 위험은 무엇인가?

AgentGuardian의 기능

AgentGuardian은 사용자가 AI 에이전트 워크플로우를 설명하면 보안 위험 검토를 생성할 수 있게 해줍니다.

사용자는 다음과 같은 정보를 입력합니다:

  • 에이전트 이름 (Agent name)
  • 에이전트 목적 (Agent purpose)
  • 에이전트가 접근 가능한 도구 (Tools the agent can access)
  • 에이전트가 처리하는 데이터 유형 (Data types the agent handles)
  • 에이전트가 받는 외부 입력 (External inputs the agent receives)
  • 자율성 수준 (Autonomy level)
  • 인간 승인 요구 사항 (Human approval requirements)

그러면 AgentGuardian은 다음을 생성합니다:

  • 0에서 100 사이의 위험 점수 (Risk score)
  • 위험 수준 (Risk level): 낮음 (Low), 중간 (Medium), 높음 (High), 또는 심각 (Critical)
  • 위험 카테고리 세부 분류 (Risk category breakdown)
  • 탐지된 위험 테이블 (Detected risks table)
  • 권장 통제 항목 (Recommended controls)
  • 로컬 LLM이 생성한 보안 요약 (Local LLM-generated security summary)
  • 다운로드 가능한 Markdown 보안 보고서 (Downloadable Markdown security report)

어떻게 생겼는지 궁금하신가요?

아키텍처 (The Architecture)

AgentGuardian은 두 개의 주요 레이어(Layer)를 가집니다.

1. 규칙 기반 위험 엔진 (Rule-Based Risk Engine)

규칙 기반 엔진은 실제 점수를 산정하는 역할을 담당합니다.

이는 의도적인 설계 선택이었습니다. LLM의 출력은 가변적일 수 있기 때문에 LLM이 위험 점수를 결정하게 하고 싶지 않았습니다. 대신, 결정론적인(Deterministic) Python 엔진이 명확한 조건에 따라 위험 점수를 할당합니다.

예를 들어:

  • 에이전트가 이메일, 업로드된 파일, 웹사이트 또는 사용자 메시지를 받는 경우, 프롬프트 인젝션 (Prompt injection) 위험이 증가합니다.
  • 에이전트가 이메일, 파일, 데이터베이스, 결제 시스템 또는 코드 실행에 접근할 수 있는 경우, 도구 오용 (Tool misuse) 위험이 증가합니다.
  • 에이전트가 금융 데이터, 건강 데이터, 자격 증명 (Credentials), 고객 기록 또는 학생 기록을 처리하는 경우, 민감한 데이터 노출 (Sensitive data exposure) 위험이 증가합니다.
  • 에이전트가 작업을 자동으로 실행할 수 있는 경우, 자율성 (Autonomy) 위험이 증가합니다.
  • 인간의 승인이 필요하지 않은 경우, 인간의 감독 (Human oversight) 위험이 증가합니다.

이를 통해 점수 산정의 설명 가능성 (Explainability)과 일관성을 높일 수 있습니다.

2. 로컬 LLM 보안 요약 (Local LLM Security Summary)

두 번째 레이어는 Ollama를 사용하여 규칙 기반 분석 결과를 바탕으로 읽기 쉬운 보안 분석을 생성합니다.

LLM은 점수를 결정하지 않습니다. LLM은 점수를 설명합니다.

이를 통해 최종 결과물을 개발자, 보안 팀, 그리고 비기술적 이해관계자(non-technical stakeholders)들이 유용하게 사용할 수 있도록 하면서도, 프로젝트를 로컬 우선(local-first) 방식으로 유지합니다.

왜 로컬 우선(Local-First)인가?

저는 이 프로젝트가 외부 API 의존성을 피하기를 원했습니다.

Ollama를 사용하면 다음과 같은 로컬 모델을 앱에서 실행할 수 있습니다:

ollama pull llama3.2

또는:

ollama pull llama3.1:8b

그 다음 Streamlit 앱이 로컬 모델을 호출하여 보안 요약(security summary)을 생성할 수 있습니다.

많은 AI 에이전트 워크플로우(agent workflows)가 민감한 비즈니스 로직, 내부 데이터 또는 비공개 사용 사례를 포함할 수 있기 때문에, 이는 보안 중심 도구로서 매우 유용합니다. 로컬 우선 접근 방식은 외부 LLM API에 대한 의존성을 줄여주며, 통제된 환경에서 프로토타입을 더 쉽게 실행할 수 있게 합니다.

Streamlit 인터페이스 구축하기

웹 앱은 Streamlit으로 구축되었습니다.

주요 인터페이스는 세 개의 탭으로 구성됩니다:

  1. 에이전트 워크플로우 스캐너 (Agent Workflow Scanner)
  2. 리스크 지식 베이스 (Risk Knowledge Base)
  3. 샘플 시나리오 (Sample Scenarios)

스캐너 탭은 에이전트 프로필을 수집합니다. 지식 베이스는 프롬프트 인젝션 (prompt injection), 도구 오용 (tool misuse), 민감한 데이터 노출 (sensitive data exposure), 과도한 자율성 (excessive autonomy), 그리고 안전하지 않은 출력 처리 (insecure output handling)와 같은 일반적인 리스크를 설명합니다. 샘플 시나리오는 사용자가 실제적인 에이전트 워크플로우로 도구를 테스트할 수 있도록 돕습니다.

중요한 사용성 개선 사항 중 하나는 사용자가 빈 양식을 제출했을 때 앱이 보고서를 생성하지 않도록 유효성 검사(validation)를 추가한 것입니다.

이 작은 체크 하나가 앱을 거친 프로토타입이 아닌, 실제로 사용 가능한 보안 도구처럼 느껴지게 만듭니다.

고위험 시나리오 예시

하나의 샘플 시나리오는 송장 결제 에이전트(invoice payment agent)입니다:

에이전트 이름:
송장 결제 에이전트

...

이 워크플로우는 다음과 같은 여러 리스크를 생성합니다:

  • 이메일 또는 업로드된 송장을 통한 프롬프트 인젝션 (Prompt injection)
  • 금융 기록 및 자격 증명을 통한 민감한 데이터 노출 (Sensitive data exposure)
  • 결제 시스템 접근을 통한 도구 오용 (Tool misuse)
  • 에이전트가 작업을 자동으로 실행할 수 있기 때문에 발생하는 과도한 자율성 (Excessive autonomy)
  • 승인이 필요하지 않기 때문에 발생하는 인간의 감독 부족 (Lack of human oversight)

AgentGuardian은 이를 높음(High) 또는 심각(Critical) 위험 시나리오로 분류하며, 인간의 승인(Human approval), 최소 권한(Least privilege), 로깅(Logging), 입력 검증(Input validation), 출력 검토(Output review)와 같은 보호 조치를 권장합니다.

다운로드 가능한 보안 보고서

Markdown 보고서 생성 기능도 추가했습니다.

보고서에는 다음 내용이 포함됩니다:

  • 에이전트 프로필 (Agent profile)
  • 위험 점수 (Risk score)
  • 위험 수준 (Risk level)
  • 위험 카테고리 세부 분류 (Risk category breakdown)
  • 탐지된 위험 (Detected risks)
  • 권장 통제 항목 (Recommended controls)
  • 로컬 LLM이 생성한 분석 (Local LLM-generated analysis)
  • 면책 조항 (Disclaimer)

이를 통해 사용자가 보안 검토 내용을 저장하거나 공유할 수 있어 앱의 유용성이 높아집니다.

교훈 (Lessons Learned)

AgentGuardian을 구축하면서 몇 가지 눈에 띄는 설계 결정 사항들이 있었습니다.

1. LLM은 결정하는 것이 아니라 설명해야 합니다

이러한 유형의 보안 도구에서는 점수 산출이 결정론적(Deterministic)이어야 한다고 생각했습니다. LLM은 요약에는 유용하지만, 핵심적인 위험 로직은 투명하고 반복 가능해야 합니다.

2. 에이전트 보안은 위험 요인들의 조합에 달려 있습니다

도구 그 자체로는 위험하지 않습니다. 데이터 유형 그 자체로도 위험하지 않습니다. 자율성(Autonomy) 그 자체로도 위험하지 않습니다.

위험은 이들이 결합될 때 증가합니다.

예를 들어:

외부 입력 (External input) + 민감한 데이터 (Sensitive data) + 영향력이 큰 도구 (High-impact tools) + 자동 실행 (Automatic execution) = 위험한 워크플로우 (Dangerous workflow)

이러한 조합 기반의 사고방식이 점수 산출 엔진(Scoring engine)의 토대가 되었습니다.

3. 로컬 우선 AI (Local-first AI)는 보안 프로토타입에 매우 유용합니다

Ollama 덕분에 외부 API 호출에 의존하지 않고도 LLM 레이어를 쉽게 추가할 수 있었습니다. 이는 데이터 민감도가 중요한 보안 중심의 유스케이스(Use case)에서 특히 유용합니다.

4. 단순한 프로토타입이라도 강력한 아이디어를 전달할 수 있습니다

AgentGuardian은 완전한 엔터프라이즈 보안 제품은 아니지만, 다음과 같은 유용한 패턴을 보여줍니다:

구조화된 입력 (Structured input) → 설명 가능한 위험 점수 산출 (Explainable risk scoring) → 로컬 LLM 분석 (Local LLM analysis) → 다운로드 가능한 보고서 (Downloadable report)

이 패턴은 더 큰 AI 거버넌스(AI governance) 또는 AI 보안 검토 워크플로우로 확장될 수 있습니다.

향후 개선 사항

가능한 다음 단계는 다음과 같습니다:

  • Streamlit 세션 상태 (session state)를 사용한 클릭 가능한 샘플 시나리오 추가
  • 위험 요소를 OWASP LLM 및 에이전트형 AI (Agentic AI) 카테고리에 더 명시적으로 매핑
  • 보고서를 PDF로 내보내기
  • Docker 지원 추가
  • 여러 에이전트 워크플로우(agent workflows)를 나란히 비교
  • 구성 가능한 위험 가중치 (risk weights) 추가
  • 기업 정책 권장 사항 추가
  • 더 많은 로컬 모델 옵션 추가
  • 위협 모델링 (threat modeling) 모드 추가

마치며

에이전트형 AI (Agentic AI) 시스템은 스스로 행동할 수 있기 때문에 강력합니다. 하지만 이는 배포 전에 보안 검토가 반드시 필요함을 의미하기도 합니다.

AgentGuardian은 이러한 검토 프로세스를 더욱 실용적이고, 설명 가능하며, 접근하기 쉽게 만들기 위한 작은 발걸음입니다.

이 프로젝트는 규칙 기반 보안 엔진 (rule-based security engine)과 로컬 LLM 레이어를 결합하여, 개발자와 보안 팀이 위험 요소가 실제 운영 문제로 이어지기 전에 에이전트의 위험성을 충분히 검토할 수 있도록 돕습니다.

GitHub 저장소: https://github.com/zosob/AgentGuardian.git

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0