Shannon은 Docker Hub에서 워커 이미지를 가져오고, 필요한 로컬 인프라를 시작하며, 대상 저장소를 임시 워커 컨테이너 내부에 읽기 전용으로 마운트하고, 결과를 로컬 워크스페이스에 기록합니다.

소스 빌드, 인증된 스캔, 제공자별 설정 및 플랫폼 관련 참고 사항은 [문서](#documentation)를 참조하세요.

> [!TIP]
> **API 크레딧 대신 구독을 사용하는 것을 선호하시나요?**
>
> - **OpenAI Codex:** 최신 버전의 Shannon은 ChatGPT Plus 및 Pro 구독을 지원합니다. 시작하려면 [OpenAI Codex 구독 설정 가이드](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md#openai-codex-chatgpt-pluspro-subscription)를 따르세요.
> - **xAI (Grok):** 최신 버전의 Shannon은 xAI 구독을 지원합니다. 시작하려면 [xAI 구독 설정 가이드](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md#xai-grok-subscription)를 따르세요.
> - **Claude Code:** 최신 버전의 Shannon은 Claude Code 구독을 지원하지 않습니다. Claude Agent SDK를 기반으로 빌드된 마지막 릴리스인 버전 `1.9.0`을 사용하려면 [Claude Code 구독 설정 가이드](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md#claude-code-subscription)를 따르세요.



## 주요 기능

- **익스플로잇 없으면 보고서도 없다**: 재현 가능한 개념 증명(proof of concept)으로 확인된 취약점만 보고하여 추측성 스캐너 노이즈를 줄입니다.
- **고급 코드 분석**: 신뢰할 수 있는 공격 경로를 라이브 펜테스팅 에이전트에 전달하기 전에 아키텍처, 신뢰 경계, 인터페이스, 데이터 흐름, 핵심 자산을 매핑합니다.
- **자율 실행**: 단일 명령으로 정찰, 분석, 익스플로잇, 보고를 실행합니다.
- **라이브 터미널 경험**: 오케스트레이션 로그를 노출하지 않고 스캔 설정을 간소화하고 에이전트 진행 상황과 결과를 보여줍니다.
- **인증된 테스트**: 구성 파일을 통해 자격 증명, 로그인 흐름, TOTP, 이메일 인증, 집중 영역, 교전 규칙을 지원합니다.
- **OWASP 중심 커버리지**: 익스플로잇 가능한 인젝션, XSS, SSRF, 취약한 인증, 취약한 인가를 테스트합니다.
- **재개 가능한 워크스페이스**: 완료된 작업을 반복하지 않고 중단된 스캔을 재개합니다.
- **네이티브 CI/CD 통합**: 공식 GitHub Action 또는 GitLab CI/CD 컴포넌트를 통해 실행되며, 아티팩트를 보존하고, 발견 사항을 게시하며, 입증된 취약점을 기준으로 릴리스를 게이팅합니다.
- **다중 형식 보고서**: 증거가 풍부한 PDF 및 Markdown 보고서와 JSON 및 SARIF 2.1.0을 생성합니다. SARIF는 익스플로잇 모드 스캔에서 기본적으로 활성화됩니다.
- **제공자 비종속 및 BYOK**: Anthropic, OpenAI, xAI, AWS Bedrock, 호환 API 및 LLM 게이트웨이, 그리고 Ollama, vLLM, LM Studio를 통해 제공되는 로컬 모델을 지원합니다.
- **설계부터 프라이빗**: 사용자의 인프라에서 실행되고, 결과를 로컬에 저장하며, 모델 요청을 선택한 엔드포인트로 직접 전송합니다. 로컬 엔드포인트를 사용하면 데이터가 사용자 환경 내에 유지됩니다.



## CI/CD 통합

Shannon은 [GitHub Actions](https://github.com/KeygraphHQ/shannon-action) 및 [GitLab CI/CD](https://gitlab.com/KeygraphHQ/shannon-ci) 공식 통합을 통해 배포된 스테이징 및 개발 환경을 대상으로 지속적으로 실행될 수 있습니다.

두 통합 모두:

- 실행 중인 대상을 공격하는 동시에 체크아웃된 소스 저장소를 분석합니다.
- PDF, Markdown, SARIF 보고서를 파이프라인 아티팩트로 보존합니다.
- 불완전한 실행을 포함하여 디버깅을 위한 스캔 및 에이전트 로그를 보존합니다.
- 풀 리퀘스트, 릴리스, 예약된 펜테스트를 지원합니다.
- 불완전한 평가와 발견 사항이 없는 완료된 스캔을 구분합니다.
- 선택적으로 Shannon이 구성된 심각도 임계값 이상의 취약점을 익스플로잇할 경우 파이프라인을 실패시킵니다.

코드 분석 가설은 파이프라인을 실패시키지 않습니다. 심각도 게이트는 `status: exploited`인 발견 사항만 집계합니다.

### GitHub Actions```yaml
name: Shannon Pentest

on:
  workflow_dispatch:

permissions:
  security-events: write

jobs:
  pentest:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run Shannon
        uses: KeygraphHQ/shannon-action@v1
        with:
          url: https://staging.example.com
          api-key: ${{ secrets.SHANNON_AI_API_KEY }}
          fail-on-severity: high
          upload-sarif: true

EXISTING -- "Pentest candidates" --> REC["Finding reconciliation<br/>(merge + deduplicate)"]
SAST -- "SAST candidates" --> REC

REC -- "Reconciled exploitation queue" --> EXP["Exploitation agents"]
APP["Running application"] --> EXP

EXP -- "Exploit demonstrated" --> REPORT["Reporting<br/>PDF · Markdown · SARIF"]
EXP -- "No exploit demonstrated" --> DROP["Discard"]

REPORT --> CICD["CI/CD gate"]

단계별로:

1. **정찰 및 취약점 분석**은 실행 중인 애플리케이션을 탐색하고, 런타임 동작을 소스 코드와 연결하며, Injection, XSS, SSRF, 인증, 인가 전반에 걸쳐 특화된 에이전트를 실행합니다.
2. **에이전틱 보안 코드 분석**은 애플리케이션의 아키텍처, 신뢰 경계, 노출된 인터페이스, 의존성, 데이터 흐름, 고위험 자산을 매핑한 뒤 이들을 대상으로 표적화된 조사를 시작합니다.
3. **발견 사항 조정**은 두 후보 스트림을 병합하고, 중복을 제거하며, 남은 항목을 익스플로잇 큐로 그룹화합니다.
4. **익스플로잇 에이전트**는 실행 중인 애플리케이션을 대상으로 실제 개념 증명 공격을 시도합니다.
5. **검증**은 Shannon이 입증할 수 없는 모든 후보를 제거합니다.
6. **보고**는 증거가 첨부된 PDF 및 Markdown 보고서와 함께 다운스트림 시스템용 구조화된 JSON 및 SARIF를 생성합니다.

실제 검증된 취약점만이 Shannon 펜테스트 발견 사항이 되거나 CI/CD 심각도 게이트에 반영됩니다.

각 스캔은 격리된 워크스페이스와 호출별 오케스트레이션을 갖춘 임시 Docker 컨테이너에서 실행됩니다.

## 문서

운영 세부 사항은 다음 가이드를 참조하세요:


| 가이드                                                     | 사용 용도                                                                                                                                                                |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [소스 빌드 및 CLI 명령](https://github.com/keygraphhq/shannon/blob/main/docs/development.md)      | 클로닝, 빌드, 일반 명령, 출력 경로, 로컬 개발.                                                                                                  |
| [구성](https://github.com/keygraphhq/shannon/blob/main/docs/configuration.md)                    | 인증된 테스트, 로그인 흐름, 교전 규칙, 보고서 필터.                                                                                              |
| [AI 제공자](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md)                      | 모델 선택, 지원되는 제공자(Anthropic, OpenAI, xAI, AWS Bedrock 및 기타 Pi 지원 제공자), 사용자 정의 LLM 게이트웨이.                             |
| [플랫폼 및 네트워킹](https://github.com/keygraphhq/shannon/blob/main/docs/platforms.md)             | Windows/WSL2, Linux, macOS, Docker 네트워킹, 로컬 앱, 사용자 정의 호스트 이름.                                                                                          |
| [워크스페이스 및 재개](https://github.com/keygraphhq/shannon/blob/main/docs/workspaces.md)             | 워크스페이스 이름 지정, 중단된 스캔 재개, 워크스페이스 저장소.                                                                                                     |
| [안전 및 제한 사항](https://github.com/keygraphhq/shannon/blob/main/docs/safety.md)                  | 승인된 사용 요건, 비프로덕션 지침, 변경 효과, 비용, 모델 주의 사항.                                                                          |
| [커버리지 및 로드맵](https://github.com/keygraphhq/shannon/blob/main/docs/coverage-roadmap.md)          | 현재 취약점 커버리지 및 계획된 작업.                                                                                                                          |
| [Keygraph Enterprise Platform](https://github.com/keygraphhq/shannon/blob/main/docs/keygraph-platform.md) | 철저한 에이전틱 SAST, 지속적 펜테스팅, 전체 수명 주기 발견 사항 관리, 교정, 표적화된 검증, 엔터프라이즈 거버넌스, 온프레미스 배포. |




## 안전, 범위 및 제한 사항

Shannon은 수동적 스캐너가 아닙니다. 익스플로잇 에이전트는 사용자를 생성하고, 양식을 제출하고, 애플리케이션 상태를 변경하고, 아웃바운드 요청을 트리거하는 등 대상 시스템에 영향을 줄 수 있습니다. 일회용 데이터가 있는 샌드박스, 스테이징 또는 로컬 개발 환경을 사용하세요.

Shannon을 합법적이고 윤리적으로 사용할 책임은 귀하에게 있습니다. 소유하지 않았거나 명시적 테스트 승인을 받지 않은 시스템, 저장소 또는 애플리케이션에 Shannon을 겨냥하지 마세요.

중요한 제한 사항:

- Shannon Open Source는 일상적인 개발 및 CI/CD에서 빠르고 코드 정보에 기반한 펜테스팅에 맞춰져 있습니다. 철저한 에이전틱 SAST, 더 넓은 스캐너 커버리지, 중앙 집중식 거버넌스, 전체 수명 주기 취약점 관리는 Keygraph Enterprise Platform을 통해 제공됩니다.
- 발견 사항에는 여전히 사람의 검토가 필요합니다. LLM이 생성한 보고서에는 근거가 약하거나 부정확한 세부 정보가 포함될 수 있습니다.
- Anthropic, OpenAI, xAI, AWS Bedrock은 내장 제공자이며, 하네스 카탈로그의 다른 제공자도 작동합니다 — 각각 프록시 또는 LLM 게이트웨이를 가리키는 사용자 정의 기본 URL을 통해 접근할 수 있습니다. 모델 성능은 다양하며, Shannon의 지침이나 도구 사용 제약을 안정적으로 따르지 않는 모델은 더 약한 결과를 생성합니다.
- 전체 실행은 대략 1~1.5시간이 걸릴 수 있으며 모델 가격과 애플리케이션 복잡도에 따라 LLM API 비용이 발생할 수 있습니다.
- 신뢰할 수 없거나 적대적인 코드베이스를 스캔하지 마세요. 소스 코드를 읽는 AI 기반 도구는 프롬프트 인젝션에 노출될 수 있습니다.

새 환경에서 Shannon을 실행하기 전에 전체 [안전 및 제한 사항](https://github.com/keygraphhq/shannon/blob/main/docs/safety.md) 가이드를 읽어보세요.

## 라이선스

Shannon Open Source는 [GNU Affero General Public License v3.0](https://github.com/keygraphhq/shannon/blob/main/LICENSE)에 따라 라이선스가 부여됩니다.

다른 라이선스 조건, 상업적 지원, 비공개 재배포, 관리형 서비스 사용 또는 Keygraph 플랫폼을 포함한 더 넓은 배포 옵션이 필요한 조직을 위해 상업 및 엔터프라이즈 라이선스를 이용할 수 있습니다.

상업적 라이선스에 대해서는 [[email protected]](mailto:[email protected])로 문의하세요.

## 감사의 글

[Pi](https://github.com/earendil-works/pi),
[Playwright CLI](https://github.com/microsoft/playwright-cli),
그리고 [Mantis](https://github.com/google/mantis)에 감사드립니다.

라이선스 및 저작자 표시 세부 사항은 [THIRD_PARTY_NOTICES.md](https://github.com/keygraphhq/shannon/blob/main/THIRD_PARTY_NOTICES.md)를 참조하세요.

## Keygraph 소개

**Keygraph**는 Shannon을 만든 회사입니다. 또한 전체 AppSec 수명 주기를 완성하고 향상된 Shannon 빌드를 펜테스팅 엔진으로 실행하는 상업용 에이전틱 펜테스팅 제품인 **Keygraph 플랫폼**도 구축합니다.

## 커뮤니티 및 지원

**커뮤니티 오피스 아워**는 버그, 배포, 구성 질문에 대한 실습 지원을 위해 제공됩니다.

- 미국/유럽: 목요일, 오전 10:00 PT
- 아시아: 목요일, 오후 2:00 IST
- [슬롯 예약](https://cal.com/george-flores-keygraph/shannon-community-office-hours)

질문하고, 피드백을 공유하고, 다른 Shannon 사용자와 연결하려면 [Discord에 참여](https://discord.gg/cmctpMBXwE)하세요.

현재 Keygraph는 외부 코드 기여를 받지 않습니다. 버그 보고 및 기능 요청을 위한 이슈는 환영합니다:

- [버그 보고](https://github.com/KeygraphHQ/shannon/issues)
- [기능 제안](https://github.com/KeygraphHQ/shannon/discussions)

계속 연결하세요:

- [Keygraph 웹사이트](https://keygraph.io)
- [Twitter/X: @KeygraphHQ](https://twitter.com/KeygraphHQ)
- [LinkedIn: Keygraph](https://linkedin.com/company/keygraph)



## 자주 묻는 질문



### Shannon을 자체 호스팅할 수 있나요?

예. Shannon Open Source는 임시 워커 컨테이너에서 귀하의 인프라 내부에서 실행됩니다. 저장소를 읽기 전용으로 마운트하고 결과를 로컬 워크스페이스에 기록합니다.

Keygraph는 귀하의 소스 코드를 절대 받지 않으며 모델 트래픽을 프록시하지 않습니다. 모델 요청은 구성한 제공자 또는 엔드포인트로 직접 전달되며, 소스 및 애플리케이션 컨텍스트를 함께 전달합니다. Shannon을 로컬에서 호스팅되는 엔드포인트로 지정하면 해당 트래픽도 귀하의 환경 내에 머뭅니다.

### Shannon은 BYOK(bring your own key)를 지원하나요?

예, 항상 그렇습니다. 오픈 소스와 상업용을 포함한 모든 배포에서 펜테스트를 실행하는 데 Shannon이 사용하는 LLM 자격 증명을 귀하가 제공합니다. Keygraph는 귀하의 모델 트래픽을 절대 프록시하지 않습니다.

### Shannon은 SARIF를 출력하나요?

예. Shannon은 구조화된 JSON과 함께 정적 분석 결과를 위한 OASIS 표준 형식인 SARIF 2.1.0을 생성합니다. 모든 SARIF 소비자가 이를 읽습니다: 코드 스캐닝 서비스, 취약점 관리 플랫폼, 보안 대시보드, CI/CD 파이프라인. 익스플로잇 모드 스캔에서 기본적으로 기록되며, 옵트아웃하려면 구성 파일에서 `report.sarif`를 `"false"`로 설정하세요.

### Shannon은 어떤 AI 제공자를 지원하나요?

Anthropic, OpenAI, xAI, AWS Bedrock은 내장되어 있으며 제공자 ID로 직접 구성됩니다. 그 외에도 Shannon은 Pi 하네스 카탈로그의 모든 제공자에서 실행되며, 동일한 `<provider>:<model-id>` 방식으로 이름이 지정됩니다. 모든 제공자는 사용자 정의 기본 URL을 통해 프록시 또는 LLM 게이트웨이로 지정할 수 있으며, 이는 엔드포인트만 재정의하고 해당 제공자의 API 방식을 유지합니다. Shannon은 펜테스트 전반에 걸쳐 단일 통합 모델 설정을 사용합니다.

### 로컬 또는 자체 호스팅 모델에서 Shannon을 실행할 수 있나요?

Shannon은 OpenAI 호환 엔드포인트를 노출하는 Ollama, vLLM 또는 LM Studio를 통해 제공되는 로컬 모델과 OpenRouter 같은 라우터 및 LiteLLM 같은 LLM 게이트웨이에서 작동합니다. 사용자 정의 기본 URL로 Shannon을 엔드포인트로 지정하세요. 성능은 다양하며, Shannon의 지침이나 도구 사용 제약을 안정적으로 따르지 않는 모델은 최전선 모델보다 더 약한 펜테스트를 생성하므로, 선택한 모델의 동작 방식을 알고 있는 경우에만 이 경로를 택하세요. [AI 제공자](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md#custom-base-url)를 참조하세요.

### Shannon은 실제로 취약점을 익스플로잇하나요, 아니면 그냥 스캔만 하나요?

Shannon은 실제 익스플로잇을 실행합니다. 작동하는 개념 증명을 생성한 경우에만 발견 사항을 보고하고, 입증할 수 없는 가설은 폐기합니다. 이는 수동적 스캐너가 아니라 펜테스터입니다.

**[Keygraph](https://keygraph.io)가 제작**