Shannon estrae l'immagine worker da Docker Hub, avvia l'infrastruttura locale richiesta, monta il repository di destinazione in sola lettura all'interno di un container worker effimero e scrive i risultati in un workspace locale.

Per build da sorgente, scansioni autenticate, configurazione specifica del provider e note sulla piattaforma, consulta la [Documentazione](#documentation).

> [!TIP]
> **Preferisci usare un abbonamento invece dei crediti API?**
>
> - **OpenAI Codex:** L'ultima versione di Shannon supporta gli abbonamenti ChatGPT Plus e Pro. Segui la [guida alla configurazione dell'abbonamento OpenAI Codex](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md#openai-codex-chatgpt-pluspro-subscription) per iniziare.
> - **xAI (Grok):** L'ultima versione di Shannon supporta gli abbonamenti xAI. Segui la [guida alla configurazione dell'abbonamento xAI](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md#xai-grok-subscription) per iniziare.
> - **Claude Code:** L'ultima versione di Shannon non supporta gli abbonamenti Claude Code. Segui la [guida alla configurazione dell'abbonamento Claude Code](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md#claude-code-subscription) per usare la versione `1.9.0`, che è l'ultima release basata su Claude Agent SDK.



## Capacità principali

- **Nessun exploit, nessun report**: Segnala solo vulnerabilità confermate con una proof of concept riproducibile, riducendo il rumore speculativo degli scanner.
- **Analisi avanzata del codice**: Mappa architettura, trust boundary, interfacce, flussi di dati e asset critici prima di inviare percorsi di attacco credibili agli agenti di pentesting live.
- **Esecuzione autonoma**: Esegue ricognizione, analisi, exploitation e reporting da un singolo comando.
- **Esperienza terminale live**: Semplifica la configurazione della scansione e mostra il progresso e i risultati degli agenti senza esporre i log di orchestrazione.
- **Test autenticati**: Supporta credenziali, flussi di login, TOTP, autenticazione email, aree di focus e regole di ingaggio tramite configurazione.
- **Copertura orientata a OWASP**: Testa injection sfruttabili, XSS, SSRF, autenticazione compromessa e autorizzazione compromessa.
- **Workspace ripristinabili**: Riprende scansioni interrotte senza ripetere il lavoro completato.
- **Integrazioni CI/CD native**: Funziona tramite la GitHub Action ufficiale o il componente GitLab CI/CD, preserva gli artefatti, pubblica i risultati e blocca le release su vulnerabilità dimostrate.
- **Report multi-formato**: Produce report PDF e Markdown ricchi di evidenze, oltre a JSON e SARIF 2.1.0. SARIF è abilitato per impostazione predefinita per le scansioni in modalità exploit.
- **Provider agnostico e BYOK**: Supporta Anthropic, OpenAI, xAI, AWS Bedrock, API compatibili e gateway LLM, e modelli locali serviti tramite Ollama, vLLM o LM Studio.
- **Privato by design**: Funziona nella tua infrastruttura, memorizza i risultati localmente e invia le richieste ai modelli direttamente all'endpoint scelto. Un endpoint locale mantiene i dati all'interno del tuo ambiente.



## Integrazioni CI/CD

Shannon può essere eseguito in modo continuo contro ambienti di staging e sviluppo distribuiti tramite integrazioni ufficiali per [GitHub Actions](https://github.com/KeygraphHQ/shannon-action) e [GitLab CI/CD](https://gitlab.com/KeygraphHQ/shannon-ci).

Entrambe le integrazioni:

- analizzano il repository sorgente estratto mentre attaccano un target in esecuzione;
- preservano i report PDF, Markdown e SARIF come artefatti della pipeline;
- preservano i log di scansione e degli agenti per il debug, incluse le esecuzioni incomplete;
- supportano pentest su pull request, release e pianificati;
- distinguono una valutazione incompleta da una scansione completata senza risultati; e
- possono facoltativamente far fallire la pipeline quando Shannon sfrutta una vulnerabilità pari o superiore a una soglia di severità configurata.

Un'ipotesi di analisi del codice non fa fallire la pipeline. Le soglie di severità contano solo i risultati con `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"]

Passo dopo passo:

1. **Ricognizione e analisi delle vulnerabilità** esplora l'applicazione in esecuzione, collega il comportamento a runtime al codice sorgente ed esegue agenti specializzati su Injection, XSS, SSRF, Autenticazione e Autorizzazione.
2. **Analisi agentica del codice di sicurezza** mappa l'architettura dell'applicazione, i confini di fiducia, le interfacce esposte, le dipendenze, i flussi di dati e gli asset ad alto rischio, quindi avvia indagini mirate su di essi.
3. **Riconciliazione dei risultati** unisce entrambi i flussi di candidati, deduplica le sovrapposizioni e raggruppa ciò che rimane in una coda di sfruttamento.
4. **Gli agenti di sfruttamento** tentano attacchi proof-of-concept reali contro l'applicazione in esecuzione.
5. **La validazione** scarta ogni candidato che Shannon non riesce a dimostrare.
6. **Il reporting** produce report in PDF e Markdown con le prove allegate, oltre a JSON strutturato e SARIF per i sistemi a valle.

Solo le vulnerabilità validate dal vivo diventano risultati del pentest di Shannon o contano ai fini delle soglie di severità CI/CD.

Ogni scansione viene eseguita in un container Docker effimero con uno workspace isolato e orchestrazione per singola invocazione.

## Documentazione

Usa queste guide per i dettagli operativi:


| Guida                                                     | Usala per                                                                                                                                                                |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Build dal sorgente e comandi CLI](https://github.com/keygraphhq/shannon/blob/main/docs/development.md)      | Clonazione, build, comandi comuni, percorsi di output e sviluppo locale.                                                                                                  |
| [Configurazione](https://github.com/keygraphhq/shannon/blob/main/docs/configuration.md)                    | Test autenticati, flussi di login, regole di ingaggio e filtri dei report.                                                                                              |
| [Provider AI](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md)                      | Selezione del modello, i provider supportati (Anthropic, OpenAI, xAI, AWS Bedrock e qualsiasi altro provider supportato da Pi) e gateway LLM personalizzati.                             |
| [Piattaforme e networking](https://github.com/keygraphhq/shannon/blob/main/docs/platforms.md)             | Windows/WSL2, Linux, macOS, networking Docker, app locali e hostname personalizzati.                                                                                          |
| [Workspace e ripresa](https://github.com/keygraphhq/shannon/blob/main/docs/workspaces.md)             | Denominazione dei workspace, ripresa di scansioni interrotte e archiviazione dei workspace.                                                                                                     |
| [Sicurezza e limitazioni](https://github.com/keygraphhq/shannon/blob/main/docs/safety.md)                  | Requisiti di uso autorizzato, indicazioni per ambienti non di produzione, effetti mutativi, costi e avvertenze sui modelli.                                                                          |
| [Copertura e roadmap](https://github.com/keygraphhq/shannon/blob/main/docs/coverage-roadmap.md)          | Copertura attuale delle vulnerabilità e lavoro pianificato.                                                                                                                          |
| [Keygraph Enterprise Platform](https://github.com/keygraphhq/shannon/blob/main/docs/keygraph-platform.md) | SAST agentico esaustivo, pentesting continuo, gestione dei risultati sull'intero ciclo di vita, remediation, verifica mirata, governance enterprise e deployment on-premises. |




## Sicurezza, Ambito e Limitazioni

Shannon non è uno scanner passivo. I suoi agenti di sfruttamento possono creare utenti, inviare form, mutare lo stato dell'applicazione, attivare richieste in uscita e in altro modo influenzare il sistema target. Usa ambienti sandbox, di staging o di sviluppo locale con dati usa e getta.

Sei responsabile di usare Shannon in modo legale ed etico. Non puntare Shannon verso sistemi, repository o applicazioni che non possiedi o per cui non hai esplicita autorizzazione a testare.

Limitazioni importanti:

- Shannon Open Source è ottimizzato per pentesting rapido e informato dal codice nello sviluppo quotidiano e nel CI/CD. SAST agentico esaustivo, copertura più ampia degli scanner, governance centralizzata e gestione delle vulnerabilità sull'intero ciclo di vita sono forniti tramite la Keygraph Enterprise Platform.
- I risultati richiedono comunque una revisione umana. I report generati da LLM possono contenere dettagli debolmente supportati o errati.
- Anthropic, OpenAI, xAI e AWS Bedrock sono provider integrati, e funziona anche qualsiasi altro provider nel catalogo dell'harness — ciascuno raggiungibile tramite un base URL personalizzato che lo indirizza verso un proxy o un gateway LLM. Le capacità dei modelli variano, e un modello che non segue in modo affidabile le istruzioni di Shannon o i vincoli sull'uso degli strumenti produrrà risultati più deboli.
- Un'esecuzione completa può richiedere circa 1-1,5 ore e può comportare costi API LLM a seconda del prezzo del modello e della complessità dell'applicazione.
- Non scansionare codebase non attendibili o ostili. Gli strumenti basati su AI che leggono il codice sorgente possono essere esposti a prompt injection.

Leggi la guida completa [Sicurezza e limitazioni](https://github.com/keygraphhq/shannon/blob/main/docs/safety.md) prima di eseguire Shannon in un nuovo ambiente.

## Licenza

Shannon Open Source è distribuito sotto la [GNU Affero General Public License v3.0](https://github.com/keygraphhq/shannon/blob/main/LICENSE).

Licenze commerciali ed enterprise sono disponibili per organizzazioni che necessitano di termini di licenza diversi, supporto commerciale, ridistribuzione privata, uso come servizio gestito o opzioni di deployment più ampie, inclusa la piattaforma Keygraph.

Per licenze commerciali, contatta [[email protected]](mailto:[email protected]).

## Riconoscimenti

Grazie a [Pi](https://github.com/earendil-works/pi),
[Playwright CLI](https://github.com/microsoft/playwright-cli),
e [Mantis](https://github.com/google/mantis).

Vedi [THIRD_PARTY_NOTICES.md](https://github.com/keygraphhq/shannon/blob/main/THIRD_PARTY_NOTICES.md) per dettagli su licenze e attribuzioni.

## Informazioni su Keygraph

**Keygraph** è l'azienda dietro Shannon. Sviluppa anche la **piattaforma Keygraph**, il prodotto commerciale di pentesting agentico che chiude l'intero ciclo di vita AppSec ed esegue una build potenziata di Shannon come motore di pentesting.

## Community e Supporto

Gli **orari di ricevimento della community** sono disponibili per assistenza pratica su bug, deployment e domande di configurazione.

- US/EU: giovedì, 10:00 PT
- Asia: giovedì, 14:00 IST
- [Prenota uno slot](https://cal.com/george-flores-keygraph/shannon-community-office-hours)

[Unisciti a Discord](https://discord.gg/cmctpMBXwE) per fare domande, condividere feedback e connetterti con altri utenti di Shannon.

Al momento, Keygraph non accetta contributi di codice esterni. Le issue sono benvenute per segnalazioni di bug e richieste di funzionalità:

- [Segnala bug](https://github.com/KeygraphHQ/shannon/issues)
- [Suggerisci funzionalità](https://github.com/KeygraphHQ/shannon/discussions)

Resta connesso:

- [Sito web Keygraph](https://keygraph.io)
- [Twitter/X: @KeygraphHQ](https://twitter.com/KeygraphHQ)
- [LinkedIn: Keygraph](https://linkedin.com/company/keygraph)



## Domande Frequenti



### Posso ospitare Shannon autonomamente?

Sì. Shannon Open Source viene eseguito all'interno della tua infrastruttura in un container worker effimero. Monta il repository in sola lettura e scrive i risultati in un workspace locale.

Keygraph non riceve mai il tuo codice sorgente e non fa mai da proxy al tuo traffico verso i modelli. Le tue richieste ai modelli vanno direttamente al provider o all'endpoint che configuri, e portano con sé il contesto del codice sorgente e dell'applicazione. Punta Shannon verso un endpoint ospitato localmente e anche quel traffico rimane all'interno del tuo ambiente.

### Shannon supporta bring your own key (BYOK)?

Sì, sempre. Fornisci tu le credenziali LLM che Shannon usa per eseguire un pentest, in ogni deployment, open source e commerciale. Keygraph non fa mai da proxy al tuo traffico verso i modelli.

### Shannon produce output SARIF?

Sì. Shannon emette SARIF 2.1.0, il formato standard OASIS per i risultati di analisi statica, insieme a JSON strutturato. Qualsiasi consumer SARIF lo legge: servizi di code scanning, piattaforme di gestione delle vulnerabilità, dashboard di sicurezza e pipeline CI/CD. Viene scritto per impostazione predefinita nelle scansioni in modalità exploit; imposta `report.sarif` su `"false"` nel tuo file di configurazione per disattivarlo.

### Quali provider AI supporta Shannon?

Anthropic, OpenAI, xAI e AWS Bedrock sono integrati e configurati direttamente tramite l'ID del provider. Oltre a questi, Shannon funziona con qualsiasi provider nel catalogo dell'harness Pi, denominato allo stesso modo `<provider>:<model-id>`. Qualsiasi provider può essere indirizzato verso un proxy o un gateway LLM tramite un base URL personalizzato, che sovrascrive solo l'endpoint e mantiene il dialetto API di quel provider. Shannon usa un'unica impostazione di modello unificata per tutto un pentest.

### Posso eseguire Shannon su un modello locale o self-hosted?

Shannon funziona con modelli locali serviti tramite Ollama, vLLM o LM Studio, che espongono un endpoint compatibile con OpenAI, così come con router come OpenRouter e gateway LLM come LiteLLM. Punta Shannon verso l'endpoint con un base URL personalizzato. Le capacità variano, e un modello che non segue in modo affidabile le istruzioni di Shannon o i vincoli sull'uso degli strumenti produrrà pentest più deboli rispetto a un modello di frontiera, quindi segui questa strada solo se sai come si comporta il modello che hai scelto. Vedi [Provider AI](https://github.com/keygraphhq/shannon/blob/main/docs/ai-providers.md#custom-base-url).

### Shannon sfrutta davvero le vulnerabilità o si limita a scansionare?

Shannon esegue exploit reali. Segnala un risultato solo quando ha prodotto un proof-of-concept funzionante, e scarta le ipotesi che non riesce a dimostrare. È un pentester, non uno scanner passivo.

**Realizzato da [Keygraph](https://keygraph.io)**