원문 캡처 · github.com
원문 캡처 · github.com

Argus 저장소는 AI 에이전트가 증거를 분석하고 보안 조사·위협 탐지를 돕되, 운영 환경을 직접 변경하지 못하도록 설계한 자체 호스팅 오픈소스 보안 운영 플랫폼이다. 시스템 변경은 정책, 승인, 시험 실행과 롤백을 거치는 별도 액션 브로커만 수행한다.

저장소의 README는 현재 구현된 기능을 설명한다. 설계는 docs/ARCHITECTURE.md, 구현 완료 항목과 향후 계획은 docs/ROADMAP.md에 정리돼 있다. Argus는 포크해 확장하는 것을 전제로 한 기반 프로젝트다. 테넌시, 인증·권한, 감사 체인, 작업 큐, 정책과 승인 등 플랫폼 핵심은 SQLite와 PostgreSQL에서 CI 엔드투엔드 테스트를 거친다. 운영 환경에 맞춰 수집기와 탐지 규칙을 조정하고, 액션을 활성화하기 전에 모니터링 전용 모드로 시작하라고 안내한다. 인증 제품은 아니며, 준수 증거로 제시할 수 있는 범위와 한계는 docs/COMPLIANCE.md에 적혀 있다.

구성과 안전 경계

수집기는 클라우드, 계정·권한, 코드, 엔드포인트, 네트워크, Kubernetes 자산을 증거 그래프로 모은다. 탐지 엔진은 스웜, 신원, 클라우드, 코드, 카나리 신호 등을 평가한다. 범위가 제한된 테스트 하네스는 승인된 보안 도구를 실행하고, 권한이 관리되는 에이전트는 읽기 전용 도구로 분류·조사·위협 탐색을 한다. 별도 액션 브로커에는 유형이 지정된 액션, 정책, 승인, 드라이런, 롤백, 킬 스위치가 있으며 시스템을 변경할 수 있는 유일한 구성 요소다.

저장소가 설명하는 신뢰 경계는 다음과 같다.

  • 에이전트는 명령을 실행할 수 없다. 에이전트의 유일한 쓰기 도구는 대기 상태의 요청을 만든다.
  • 에이전트가 읽는 모든 자료는 신뢰할 수 없는 데이터로 감싸며, 프롬프트는 이를 모델에 알린다.
  • 능동 테스트는 기록된 승인과 범위 안에서만 실행되며, 실행 시점에 조건을 다시 확인한다.
  • 모든 도메인 테이블에 tenant_id가 있고, 쿼리는 범위가 제한된 헬퍼를 거친다. 테스트도 이를 확인한다.
  • 감사 체인은 해시로 연결되고 HMAC 서명을 사용한다. 운영 환경에서는 서명이 필수이며, 체인은 외부 저장소에도 복제할 수 있다. 저장소는 선택적으로 WORM 방식도 지원한다.

구현된 기능

영역상태와 범위
애플리케이션 기반앱 팩토리, 설정, 데이터베이스, RBAC, 로컬·OIDC·TOTP·API 키 인증, CSRF, 요청 속도 제한을 구현하고 테스트했다. app/core/, app/api/auth.py, app/api/deps.py에 있다.
감사·작업 처리JSONL, S3 Object Lock, Azure 불변 블롭 저장소를 지원하는 감사 체인을 구현했다. 인메모리·Redis 큐는 임대, 재시도, 취소, 정리 작업과 독립 워커를 지원한다. app/core/audit.py, app/core/queue.py, app/worker.py에 있다.
관측성Prometheus 메트릭, JSON 로깅, 선택적 OpenTelemetry 추적을 지원한다. app/core/telemetry.py에 있다.
증거 그래프·탐지그래프는 노드, 간선, 공격 경로, 노출 점수를 다룬다. 탐지에는 스웜 4개, 신원 2개, 클라우드, Kubernetes, 코드, 카나리, 이상 징후, 에이전트형 탐지 등 12개 규칙과 기준선·카나리가 있다. app/graph/, app/detections/ 등에 있다.
수집기AWS, Azure, GCP, Kubernetes, GitHub, Okta, Entra, osquery, netflow 수집기를 픽스처와 함께 구현했다. 클라우드 SDK는 선택 사항이다. app/collectors/에 있다.
테스트 하네스범위 정책과 속도 제한을 지원한다. 웹 기준선, trivy, nuclei, zap, prowler, caldera, semgrep, gitleaks용 어댑터가 구현돼 있지만 도구는 별도로 설치해야 한다. app/testing/에 있다.
에이전트Anthropic, OpenAI, Ollama, 공급자 없음 설정과 읽기 전용 도구, 전문 에이전트 7종, 평가 제품군을 구현했다. app/agents/에 있다.
액션 브로커AWS, Azure, GCP, Kubernetes, GitHub, Okta, Entra, Cloudflare, Argus 내부 액션을 포함한 유형 지정 액션 25개와 정책, 승인, 드라이런, 실행, 롤백, 킬 스위치를 구현했다. app/actions/에 있다.
연동·APIPOST /api/v1/ingest/{source} 뒤에 입력 파서 13개를 두고, 웹훅, Slack, Jira, ServiceNow, PagerDuty, 이메일 등 출력 채널 6개에 전달·재시도를 구현했다. Wazuh 인덱서에서 가져오기도 지원한다. 관리, 자산, 발견 사항, 이벤트, 조사, 승인, 감사, 보고서 라우터도 구현했다.
배포·마이그레이션초기 Alembic 마이그레이션과 scripts/migrate.py, 컨테이너, Compose, Helm, AWS·Azure Terraform, CI, 관측성, 문서를 제공한다. 라우터는 자동 검색되며 전체 v1 API는 docs/API.md에 정리돼 있다.

개발 환경에서 시작하기

개발용 빠른 시작은 Docker 없이 SQLite를 사용하며 Python 3.11 또는 3.12가 필요하다.

text
python -m venv .venv && . .venv/bin/activate # Windows: .venv\\Scripts\\activate
pip install -r requirements.txt -r requirements-dev.txt
cp .env.example .env
python scripts/generate_secrets.py --write # fills the three REPLACE_ values, plus AUDIT_SIGNING_KEY and DATA_ENCRYPTION_KEY when they are empty
uvicorn app.main:app --host 127.0.0.1 --port 8080

http://127.0.0.1:8080/을 열고 .env의 ADMIN_EMAIL과 ADMIN_PASSWORD로 로그인한다. REDIS_URL이 비어 있으면 작업은 API 프로세스 안에서 실행되며 WORKERS_INPROCESS=true가 적용된다. 기본값인 DB_AUTO_CREATE=true에서는 시작 시 테이블을 만든다. Alembic으로 관리하는 스키마를 쓰려면 이를 false로 바꾸고 python scripts/migrate.py를 실행한다. 자세한 내용은 docs/MIGRATIONS.md에 있다.

네트워크에 접속하지 않는 격리 테넌트에 합성 데모 데이터를 만들려면 다음 명령을 실행한다.

text
python scripts/seed_demo.py

명령은 demo 테넌트 로그인 정보를 출력하고 DEMO 표시가 붙은 자산, 승인 정보, 이벤트, 발견 사항, 카나리, 에이전트 실행 기록을 만든다. 이벤트에는 cloud.public_exposure_change와 swarm.machine_speed_sequence 탐지 조건을 일으키는 항목이 포함된다. APP_ENV=production이면 실행을 거부한다. 테스트 명령은 다음과 같다.

text
python -m pytest -q

Compose 파일럿과 운영 배포

파일럿은 Docker Compose로 API, 워커, PostgreSQL, Redis를 띄운다.

text
cp .env.example .env && python scripts/generate_secrets.py --write
docker compose up --build -d
docker compose logs -f api

compose.yaml은 API를 127.0.0.1:8080에만 바인딩한다. API와 워커는 읽기 전용 루트 파일시스템, 추가 권한과 Docker 소켓 없이 같은 이미지에서 실행된다. ./targets는 읽기 전용으로 마운트하며 API 시작 시 스키마를 적용한다(RUN_MIGRATIONS=true). --profile observability를 추가하면 OpenTelemetry 수집기, /metrics를 수집하는 Prometheus, infra/grafana/argus.json 대시보드가 포함된 Grafana를 띄운다.

단일 호스트에서 TLS를 종료하는 설정과 실행 명령은 다음과 같다.

text
# .env: APP_ENV=production COOKIE_SECURE=true BASE_URL=https://host ARGUS_DOMAIN=host ACME_EMAIL=ops@example.com
docker compose -f compose.yaml -f compose.prod.yaml up -d

Kubernetes 배포 파일은 infra/helm/argus에 있다. API·워커 배포, HPA, PDB, 기본 거부 네트워크 정책, TLS 인그레스와 선택적 ServiceMonitor를 포함한다. AWS용 infra/terraform은 ECS Fargate, RDS, ElastiCache, S3 Object Lock 감사 버킷, Secrets Manager, ALB와 WAF를 구성한다. Azure용 infra/terraform-azure는 Container Apps, Flexible Postgres, Azure Cache, 불변 블롭 컨테이너, Key Vault, Front Door와 WAF를 구성한다.

운영 배포 점검표는 docs/DEPLOYMENT.md에 있다. 시작 시 assert_safe_config()가 일부 조건을 강제한다. APP_ENV=production에서는 PostgreSQL, REDIS_URL, COOKIE_SECURE=true, https://로 시작하는 BASE_URL, DATA_ENCRYPTION_KEY(S), AUDIT_SIGNING_KEY(S), 외부 감사 저장소, OIDC 또는 TOTP_REQUIRED=true가 없으면 시작을 거부한다. 전용 워커를 사용하려면 WORKERS_INPROCESS=false로 설정하고 python -m app.worker를 실행한다. 감사 로그에는 JSONL만 쓰기보다 S3 Object Lock이나 Azure 불변 블롭 저장소를 사용하라고 안내한다. 엣지에서 /metrics를 차단하고 워커의 외부 통신을 필터링하며, 비밀 값은 비밀 관리 서비스에 둬야 한다. 이미지는 다이제스트로 고정하고 cosign으로 검증한다(.github/workflows/release.yml).

권한과 에이전트·테스트·액션 통제

역할은 누적형이며 app/core/rbac.py에 정의돼 있다. viewer는 테넌트의 모든 정보를 읽는다. analyst는 발견 사항과 탐지 규칙을 수정하고, 에이전트와 평가를 실행하며, 카나리를 관리하고 승인을 기록한다. operator는 자산을 관리·승인하고 테스트, 스캔, 수집기를 실행하며, 액션을 요청·승인·실행·롤백하고 탐지를 실행한다. admin은 사용자, API 키, 설정, 수집기·연동 구성, 액션 킬 스위치, 테스트 범위를 관리한다. owner는 테넌트 설정을 관리하고 중요 액션을 승인한다. API 키에는 역할과 선택적 범위(예: ingest)를 지정해 권한을 더 제한할 수 있다. system 주체는 큐 핸들러 내부에서만 사용한다.

에이전트 런타임은 app/agents/runtime.py에 있다. 전문 에이전트는 시스템 프롬프트, 도구 이름 목록, 출력 스키마, 사용량 한도를 담은 AgentSpec으로 정의한다. 한도는 AGENT_MAX_STEPS, AGENT_MAX_TOKENS, AGENT_MAX_SECONDS, AGENT_COST_CEILING_USD로 설정하며, 기본 Claude 가격표에 없는 모델에는 AGENT_MODEL_PRICES를 쓴다. 도구는 Argus 데이터에 대한 읽기 전용 뷰다. 유일한 propose 도구는 브로커를 통해 대기 상태의 ActionRequest를 만든다. 도구 결과는 모두 가림 처리하고 길이를 제한한 뒤 <untrusted_data source=...>로 감싼다. 가드레일 프롬프트는 증거에 포함된 지시를 프롬프트 인젝션 징후로 취급하라고 모델에 알린다. 각 모델·도구 단계는 입력 해시, 토큰 수, 지연 시간과 함께 agent_steps에 저장된다. AI_PROVIDER=none이면 전문 에이전트는 결정론적 대체 동작을 수행한다. 프롬프트 인젝션과 정밀도 평가 제품군은 app/agents/evals/suites/에 있다.

테스트 하네스(app/testing/)의 TestScope는 대상 자산, 허용 단계(passive, active, intrusive), 환경, UTC 기준 실행 시간대, 속도 제한, 동시 실행 제한을 지정한다. max_concurrency를 넘는 실행은 큐에서 대기한다. 자산에 해당 단계를 허용하는 최신 AssetAuthorization이 있고, 범위가 허용하며, 실행 시간대가 열려 있고, 대상이 정책 검증을 통과해야만 실행할 수 있다. scope.check()는 요청 시점과 워커 내부에서 다시 실행한다. intrusive 단계는 staging 및 lab 환경으로 제한된다. 외부 도구는 고정된 argv, 시간 제한, 출력 크기 제한, 최소 환경을 적용하는 run_tool()을 거쳐 실행한다.

액션(app/actions/)은 위험도, 되돌릴 수 있는지 여부, 매개변수 스키마를 선언하고 dry_run, execute, rollback을 구현한다. 운영자나 에이전트의 propose_action이 만든 요청은 정책을 통과해야 한다. 정책에는 킬 스위치, 테넌트의 actions_enabled, 거부 목록, 점검 시간이 포함된다. 자동 승인은 ACTIONS_AUTO_APPROVE_LOW가 설정된 경우에만 위험도가 낮고 되돌릴 수 있는 액션에 적용된다. 승인자는 요청자와 달라야 한다. ACTIONS_REQUIRE_TWO_FOR_HIGH가 설정되면 고위험 액션에 승인자 2명이 필요하고, 중요 액션에는 actions:approve_critical 권한을 가진 주체도 필요하다.

승인 뒤에는 영향 범위를 표시하는 드라이런을 거치고, 롤백 정보를 저장한 actions.execute 큐 작업으로 실행한다. 모든 상태 전이는 감사 기록에 남는다. 전역 환경 설정 ACTIONS_KILL_SWITCH=true 또는 POST /api/v1/actions/kill-switch를 통한 테넌트별 킬 스위치(actions_enabled=false)는 모든 요청과 실행을 거부한다.

문서·보안·라이선스

문서에는 아키텍처와 데이터 모델(docs/ARCHITECTURE.md), v1 경로와 상태(docs/API.md), 개발·Compose·Kubernetes·AWS·Azure 배포(docs/DEPLOYMENT.md), 모니터링 전용 운영 전환 절차(docs/GO-LIVE.md), 구현된 보안 모델과 신고 방법(docs/SECURITY.md), 신뢰 경계별 STRIDE·프롬프트 인젝션·SSRF·테넌시·자격 증명·브로커 악용·공급망 위협 모델(docs/THREAT-MODEL.md), 사고 대응 절차(docs/RUNBOOKS.md), 준수 통제 항목 매핑(docs/COMPLIANCE.md), 구현 현황과 다음 계획(docs/ROADMAP.md), 기여 안내(CONTRIBUTING.md)가 포함된다. SOC 2, NIST 800-171, ISO 27001 매핑은 증거 지원을 위한 것이며 인증을 뜻하지 않는다.

취약점은 공개 이슈가 아니라 GitHub의 비공개 취약점 신고(Security 탭)로 보고하라고 안내한다. 저장소 라이선스는 MIT다. nuclei, ZAP, Prowler, CALDERA, Semgrep, Gitleaks, Trivy와 클라우드 SDK, 모델 공급자는 각각 별도의 라이선스와 이용 약관을 따른다.