adithyan-ak/AgentHound

Offensive security framework for AI agent infrastructure - recon, credential looting, model exfiltration, poisoning, and attack-path analysis across MCP, A2A, gateways, and AI services. BloodHound for the agentic stack.

AgentHound – AI 에이전트 인프라스트럭처를 위한 오프렌시브 보안 프레임워크

무엇인가요 – AgentHound는 빨간팀 운영자가 현대의 LLM 기반 어시스턴트(Claude, Cursor, VS Code 확장, Ollama, LiteLLM, Qdrant, MLflow, Jupyter 등)를 구성하는 "에이전트 스택" 전체를 열거, 검증, 공격할 수 있게 해주는 오픈소스 도구입니다. 해킹된 호스트의 포트홀드에서 작동하며, 구성 파일, 시크릿, 접근 가능한 AI 서비스를 수집하고, 발견된 자격 증명을 재사용하며, 실제 접근을 검증하고, 모든 정보를 단일 체크포인트가 있는 JSON 아티팩트에 저장합니다. 선택적인 서버는 해당 아티팩트를 수신하여 자격 증명 체인, 실행 및 유출 경로, 위험 점수를 포함한 그래프 기반의 공격 표면을 웹 UI로 제공합니다.

핵심 워크플로우

정적 컬렉터 배포 – 해킹된 머신에 정적 바이너리(단일 바이너리, DB나 런타임 의존성 없음)를 배포합니다.
agenthound scan 실행 – 컬렉터는 로컬 에이전트 설정, 환경 시크릿, 루프백 서비스, 그리고 (옵션으로) 네트워크 범위를 수집합니다. AI 서비스를 식별하고, 캡처된 API 키나 토큰을 재사용하며, 검증된 읽기(익명 읽기 먼저, 그 후 자격 증명 사용)를 수행하여 접근을 증명합니다.
JSON 아티팩트 생성 – 모든 자격 증명, 서비스 식별 정보, 접근 증거, 각 단계 후 체크포인트를 포함하는 아티팩트를 생성합니다.
(옵션) 분석 서버 시작 – 별도의 머신에서 서버를 시작하고 아티팩트를 수신한 후 웹 UI를 통해 Neo4j 기반의 공격 그래프를 탐색합니다. 그래프는 접근 가능한 리소스, 실행 능력, 유출 경로, 크로스 프로토콜 피보팅, 그리고 오염된 지시 파일을 보여줍니다.

주요 기능

기능	설명
포트홀드 우선 자율 수집	원격 데이터베이스 없이 로컬 에이전트 설정 파일, 지시 파일, 환경 변수, 루프백 서비스, 명시적으로 제공된 네트워크 범위를 수집합니다.
원시 자격 증명 캡처 및 재사용	API 키, 베어러 토큰, Jupyter 토큰, 마스터 키와 같은 구체적인 시크릿을 중복 제거하여 저장하고, 동일한 스캔 중 발견된 호환 서비스에 즉시 시도합니다.
증거 기반 접근 검증	먼저 익명 읽기를 수행; 실패하면 자격 증명을 사용해 재시도합니다. 자격 증명 사용 시 성공한 읽기는 스캔 중 검증됨으로 기록됩니다.
역전 가능한 활성 검증	ContextForge 관리 도구의 경우, 일시적인 마커를 쓰고 MCP를 통해 다시 읽은 후 원래 상태로 복원합니다. 롤백이 확인된 후에만 진행합니다.
풀스펙트럼 에이전트 표면 매핑	MCP, A2A, 12가지 에이전트-클라이언트 설정 형식, 모델 게이트웨이, 추론 서버, 벡터 스토어, 모델 레지스트리, 노트북, 웹 인터페이스를 하나의 연결된 타겟 세트로 탐지 및 인벤토리화합니다.
심층 서비스 및 모델 인텔리전스	Ollama 모델, modelfiles, 프롬프트 목록; LiteLLM 자격 증명 참조 추출; MLflow 실험 열거; Qdrant 컬렉션 발견; Jupyter 세션 검사. deep 모드에서는 제한된 Ollama 임베딩 요청을 호출해 컴퓨팅 접근을 증명할 수 있습니다.
그래프 기반 공격 경로 분석	서버는 신뢰, 인증, 자격 증명 재사용, 도구 능력, 관측된 증거를 연결하는 Neo4j 그래프를 구축합니다. 운영자는 도달 가능성, 실행, 유출, 위조, 오염 등을 쿼리할 수 있습니다.
접근 상실에 대한 내성성	컬렉터는 의미 있는 모든 동작 후 아티팩트를 체크포인트합니다; 변경이 실패하면 롤백하고 마지막 체크포인트에서 재시작할 수 있습니다.

작동 모드

모드	동작
`agenthound scan` (기본값)	활성 수집: 자격 증명 재사용, MCP 검증, 역전 가능한 ContextForge 검증, 그리고 해당 시 모델 호출.
`agenthound scan --deep`	재귀적 지시 발견, 제한된 Qdrant 포인트 읽기, Ollama 임베딩 검증과 같은 고비용 서비스 프로브 추가.
`agenthound scan --stealth`	읽기 전용 수집: 크로스 타겟 자격 증명 재사용 없음, 모델/도구 호출 없음, 변경 없음. 익명 및 정확한 설정 읽기만 수행.
`agenthound scan --stealth --deep`	stealth와 동일하지만, 비대화형 수집을 유지하면서도 심층 파일 시스템 읽기를 수행.

빠른 시작 (README에서)

# 정적 바이너리 설치 (macOS/Linux, amd64/arm64)
curl -sSfL https://raw.githubusercontent.com/adithyan-ak/agenthound/1.1.1/install.sh \
  | AGENTHOUND_VERSION=1.1.1 sh
export PATH="$HOME/.local/bin:$PATH"

# 포트홀드에서 기본 스캔 실행
agenthound scan --output scan.json

# 옵션: Docker Compose로 분석 서버 시작
curl -sSfL https://raw.githubusercontent.com/adithyan-ak/agenthound/1.1.1/docker/docker-compose.public.yml \
  -o agenthound-compose.yml
docker compose -f agenthound-compose.yml -p agenthound up -d --wait
docker compose -f agenthound-compose.yml -p agenthound exec -T agenthound \
  agenthound-server ingest - < scan.json

# UI 열기
open http://127.0.0.1:8080

스캔에서 얻는 것들

발견 유형	해결할 수 있는 예시 질문
검증된 자격 증명 접근	어떤 정확한 시크릿이 어떤 MCP 리소스에 접근을 증명했나요?
자격 증명 체인 경로	캡처된 API 키가 에이전트 설정과 모델 게이트웨이를 어떻게 연결하나요?
도달 가능성	현재 신뢰 및 인증 링크를 따라 어떤 서비스에 도달할 수 있나요?
실행 경로	어떤 에이전트가 쉘 또는 데이터베이스 도구를 호출할 수 있나요?
유출 경로	환경 외부로 민감한 데이터를 보낼 수 있는 장소는 어디인가요?
크로스 프로토콜 피보팅	A2A 위임을 사용해 벡터 스토어에 도달할 수 있나요?
지시 오염	어떤 지시 파일에 프롬프트 인젝션 또는 오염된 컨텍스트의 증거가 있나요?
도구 그림자 / 루그 풀스	예상 기능을 가로채는 유사한 도구가 있나요?
인증 없이 노출된 표면	어떤 서비스가 인증 없이 데이터를 공개하나요?
위험 핫스팟	어떤 노드나 경로가 가장 높은 영향 점수를 가지나요?

안전성 및 OPSEC 주의사항 (README에서)

허가된 사용만 – 소유하거나 명시적 허가를 받은 시스템에만 실행하세요.
활성 모드는 자격 증명 재사용 및 역전 가능한 변경을 수행합니다; 은밀함이 필요할 경우 --stealth를 사용해 읽기 전용 수집을 수행하세요.
하드 제외 (--exclude)는 원하지 않는 호스트나 URL에 실수로 접근하는 것을 방지합니다.
즉시 복구 – 모든 변경은 다음 단계 전에 되돌아갑니다; 정리 실패 시 아티팩트에 상태가 기록되어 안전하게 재시도할 수 있습니다.
평문 증거 – JSON 아티팩트에는 원시 시크릿과 응답이 포함됩니다; 웹 UI는 기본적으로 마스킹하지만, 클릭으로 표시할 수 있습니다.

문서 및 기여

전체 문서: https://docs.agenthound.io
빠른 시작, 스캐너, CLI, 공격 경로, 배포, 보안 가이드는 모두 docs/ 폴더에 있습니다.
새로운 서비스를 지원하기 위한 모듈을 추가할 수 있습니다; CONTRIBUTING.md 및 docs/contributing/modules.md를 참조하세요.
Apache-2.0 라이선스; 취약성 보고는 SECURITY.md로.

결론 – AgentHound는 현대의 LLM 기반 어시스턴트를 네트워크 기반 공격 표면으로 간주하는 목적에 특화된 오프렌시브 프레임워크입니다. 자격 증명 수확, 증거 기반 검증, 그래프 수준 분석을 자동화하여 빨간팀이 단일 아티팩트와 시각적 UI로 전체 에이전트 스택을 이해하고 공격할 수 있도록 합니다.