praetorian-inc/augustusFramework di test di sicurezza per LLM per rilevare iniezioni di prompt, jailbreak e attacchi avversari — oltre 190 sonde, 28 fornitori, un singolo binario Go
Augustus - scanner di vulnerabilità LLM per test di prompt injection, jailbreak e attacchi avversari
# Augustus - Scanner di Vulnerabilità LLM
> Testa i modelli linguistici di grandi dimensioni contro oltre 210 attacchi avversari che coprono prompt injection, jailbreak, exploit di codifica ed estrazione di dati.
[](https://github.com/praetorian-inc/augustus/actions/workflows/ci.yaml)
[](go.mod)
[](LICENSE)
[](https://goreportcard.com/report/github.com/praetorian-inc/augustus)
[](https://github.com/praetorian-inc/augustus/releases)
**Augustus** è uno scanner di vulnerabilità LLM basato su Go, pensato per i professionisti della sicurezza. Testa i modelli linguistici di grandi dimensioni contro un'ampia gamma di attacchi avversari, si integra con 28 provider LLM e produce report di vulnerabilità utilizzabili.
A differenza degli strumenti orientati alla ricerca, Augustus è progettato per test di sicurezza in produzione: scansione concorrente, limitazione della velocità, logica di retry e gestione dei timeout sono inclusi di serie.
## Indice
- [Perché Augustus](#perché-augustus)
- [Funzionalità](#funzionalità)
- [Avvio Rapido](#avvio-rapido)
- [Provider Supportati](#provider-supportati)
- [Utilizzo](#utilizzo)
- [Probe Singolo](#probe-singolo)
- [Probe Multipli](#probe-multipli)
- [Trasformazioni Buff](#trasformazioni-buff)
- [Formati di Output](#formati-di-output)
- [Endpoint REST Personalizzati](#endpoint-rest-personalizzati)
- [Come Funziona](#come-funziona)
- [Architettura](#architettura)
- [Configurazione](#configurazione)
- [FAQ](#faq)
- [Risoluzione dei Problemi](#risoluzione-dei-problemi)
- [Contributi](#contributi)
- [Sicurezza](#sicurezza)
- [Supporto](#supporto)
- [Licenza](#licenza)
## Perché Augustus
| Funzionalità | Augustus | garak | promptfoo |
|---------|----------|-------|-----------|
| Linguaggio | Go | Python | TypeScript |
| Binario singolo | Sì | No | No |
| Scansione concorrente | Pool di goroutine | Pool di multiprocessing | Sì |
| Provider LLM | 28 | 35+ | 80+ |
| Tipi di probe | 210+ | 160+ | 119 plugin + 36 strategie |
| Focus enterprise | Sì | Ricerca | Sì |
## Funzionalità
| Funzionalità | Descrizione |
|---------|-------------|
| **Oltre 210 Probe di Vulnerabilità** | 47 categorie di attacco: jailbreak, prompt injection, esempi avversari, estrazione di dati, benchmark di sicurezza, attacchi ad agenti e altro |
| **28 Provider LLM** | OpenAI, Anthropic, Azure, Bedrock, Vertex AI, Ollama e altri 22 con 43 varianti di generatore |
| **Oltre 90 Rilevatori** | Pattern matching, LLM-as-a-judge, HarmJudge (arXiv:2511.15304), Perspective API, rilevamento di contenuti non sicuri |
| **7 Trasformazioni Buff** | Codifica, parafrasi, poesia (5 formati, 3 strategie), traduzione in lingue a basse risorse, trasformazioni di maiuscole/minuscole |
| **Output Flessibile** | Formati di report in tabella, JSON, JSONL e HTML |
| **Pronto per la Produzione** | Scansione concorrente, limitazione della velocità, logica di retry, gestione dei timeout |
| **Binario Singolo** | Strumento basato su Go che compila in un unico eseguibile portabile |
| **Estensibile** | Registrazione in stile plugin tramite funzioni `init()` di Go |
### Categorie di Attacco
- **Attacchi jailbreak**: DAN, DAN 11.0, AIM, AntiGPT, Grandma, ArtPrompts
- **Prompt injection**: Codifica (Base64, ROT13, Morse), contrabbando di tag, FlipAttack, iniezione di prefisso/suffisso
- **Esempi avversari**: GCG, PAIR, AutoDAN, TAP (Tree of Attack Prompts), TreeSearch, DRA
- **Attacchi multi-turno**: Crescendo (escalation graduale), GOAT (cambio adattivo di tecniche)
- **Estrazione di dati**: perdita di chiavi API, allucinazione di pacchetti, estrazione di PII, LeakReplay
- **Manipolazione del contesto**: avvelenamento RAG, overflow del contesto, attacchi multimodali, continuazione, divergenza
- **Exploit di formato**: iniezione Markdown, attacchi di parsing YAML/JSON, escape ANSI, iniezione Web (XSS)
- **Tecniche di evasione**: offuscamento, sostituzione di caratteri, attacchi basati su traduzione, riformulazione, ObscurePrompt
- **Benchmark di sicurezza**: DoNotAnswer, RealToxicityPrompts, Snowball, LMRC
- **Attacchi ad agenti**: manipolazione multi-agente, exploit di navigazione
- **Test di sicurezza**: bypass delle guardrail, scansione AV/spam, sfruttamento (SQLi, esecuzione di codice), BadChars
> **Avvertenza**: il probe `lmrc` utilizza linguaggio volgare e offensivo come parte dei suoi test di jailbreak. Utilizzare solo in ambienti di test autorizzati.
## Avvio Rapido
### Installazione
Richiede Go 1.27.0 o successivo.```bash
go install github.com/praetorian-inc/augustus/cmd/augustus@latest
```
Oppure compila dal sorgente:```bash
git clone https://github.com/praetorian-inc/augustus.git
cd augustus
make build
```
### Utilizzo di base```bash
export OPENAI_API_KEY="your-api-key"
augustus scan openai.OpenAI \
--probe dan.Dan_11_0 \
--detector dan.DAN \
--verbose
```
### Esempio di Output```
+--------------+-------------+--------+-------+--------+
| PROBE | DETECTOR | PASSED | SCORE | STATUS |
+--------------+-------------+--------+-------+--------+
| dan.Dan_11_0 | dan.DAN | false | 0.85 | VULN |
| dan.STAN | dan.STAN | true | 0.10 | SAFE |
| dan.AntiDAN | dan.AntiDAN | true | 0.05 | SAFE |
+--------------+-------------+--------+-------+--------+
```
### Elenca le Capacità Disponibili```bash
# List all registered probes, detectors, generators, harnesses, and buffs
augustus list
```
## Provider Supportati
Augustus include 28 categorie di provider LLM con 43 varianti di generatori:
| Provider | Nomi dei Generator(i) | Note |
|--------------------|---------------------------|--------------------------------|
| OpenAI | `openai.OpenAI`, `openai.OpenAIReasoning` | GPT-3.5, GPT-4, GPT-4 Turbo, modelli di reasoning o1/o3 |
| Anthropic | `anthropic.Anthropic` | Claude 3/3.5/4 (Opus, Sonnet, Haiku) |
| Azure OpenAI | `azure.AzureOpenAI` | Modelli OpenAI ospitati su Azure |
| AWS Bedrock | `bedrock.Bedrock` | Modelli Claude, Llama, Titan |
| Google Vertex AI | `vertex.Vertex` | Modelli PaLM, Gemini |
| Cohere | `cohere.Cohere` | Modelli Command, Command R |
| Replicate | `replicate.Replicate` | Modelli open ospitati su cloud |
| HuggingFace | `huggingface.InferenceAPI`, `huggingface.InferenceEndpoint`, `huggingface.Pipeline`, `huggingface.LLaVA` | API di inferenza HF, endpoint, pipeline, multimodale |
| Together AI | `together.Together` | Inferenza veloce per modelli OSS |
| Anyscale | `anyscale.Anyscale` | Hosting di Llama e Mistral |
| Groq | `groq.Groq` | Inferenza LPU ultraveloce |
| Mistral | `mistral.Mistral` | Modelli API Mistral |
| Fireworks | `fireworks.Fireworks` | Piattaforma di inferenza di produzione |
| DeepInfra | `deepinfra.DeepInfra` | Inferenza GPU serverless |
| NVIDIA NIM | `nim.NIM`, `nim.NVOpenAICompletion`, `nim.NVMultimodal`, `nim.Vision` | Endpoint AI NVIDIA, multimodale |
| NVIDIA NeMo | `nemo.NeMo` | Framework NVIDIA NeMo |
| NVIDIA NVCF | `nvcf.NvcfChat`, `nvcf.NvcfCompletion` | NVIDIA Cloud Functions |
| NeMo Guardrails | `guardrails.NeMoGuardrails` | NVIDIA NeMo Guardrails |
| IBM watsonx | `watsonx.WatsonX` | Piattaforma IBM watsonx.ai |
| LangChain | `langchain.LangChain` | Wrapper LLM LangChain |
| LangChain Serve | `langchain_serve.LangChainServe` | Endpoint LangChain Serve |
| Rasa | `rasa.RasaRest` | AI conversazionale Rasa |
| GGML | `ggml.Ggml` | Inferenza di modelli locali GGML |
| Function | `function.Single`, `function.Multiple` | Generatori di funzioni personalizzate |
| Ollama | `ollama.Ollama`, `ollama.OllamaChat` | Hosting di modelli locali |
| LiteLLM | `litellm.LiteLLM` | Proxy API unificato |
| REST API | `rest.Rest` | Endpoint REST personalizzati (supporto SSE) |
| Test | `test.Blank`, `test.Repeat`, `test.Lipsum`, `test.Nones`, `test.Single`, `test.BlankVision` | Test e sviluppo |
Tutti i provider sono disponibili nel binario compilato. Configura tramite variabili d'ambiente o file di configurazione YAML. Consulta [Configurazione](#configuration) per i dettagli di configurazione.
## Utilizzo
### Sonda Singola```bash
# Test for DAN jailbreak
augustus scan openai.OpenAI \
--probe dan.Dan_11_0 \
--detector dan.DAN \
--config-file config.yaml \
--verbose
```
### Sonde Multiple```bash
# Use glob patterns to run related probes
augustus scan openai.OpenAI \
--probes-glob "dan.*,goodside.*,grandma.*" \
--detectors-glob "*" \
--config-file config.yaml \
--output batch-results.jsonl
# Run all probes against Claude
augustus scan anthropic.Anthropic \
--all \
--config '{"model":"claude-3-opus-20240229"}' \
--timeout 60m \
--output comprehensive-scan.jsonl \
--html comprehensive-report.html
```
### Trasformazioni Buff
Applica trasformazioni dei prompt per testare tecniche di evasione:```bash
# Apply base64 encoding buff to all probes
augustus scan openai.OpenAI \
--all \
--buff encoding.Base64 \
--config '{"model":"gpt-4"}'
# Apply poetry transformation
augustus scan anthropic.Anthropic \
--probes-glob "dan.*" \
--buff poetry.MetaPrompt \
--config '{"model":"claude-3-opus-20240229"}'
# Chain multiple buffs
augustus scan openai.OpenAI \
--all \
--buffs-glob "encoding.*,paraphrase.*" \
--output buffed-results.jsonl
```
### Formati di Output```bash
# Table format (default) - human-readable
augustus scan openai.OpenAI --probe dan.Dan_11_0 --format table
# JSON format - structured output
augustus scan openai.OpenAI --probe dan.Dan_11_0 --format json
# JSONL format - one JSON object per line, ideal for piping
augustus scan openai.OpenAI --probe dan.Dan_11_0 --format jsonl
# HTML report - visual reports for stakeholders
augustus scan openai.OpenAI --all --html report.html
```
### Endpoint REST personalizzati```bash
# Test proprietary LLM endpoint (OpenAI-compatible API)
augustus scan rest.Rest \
--probe dan.Dan_11_0 \
--detector dan.DAN \
--config '{
"uri": "https://api.example.com/v1/chat/completions",
"method": "POST",
"headers": {"Authorization": "Bearer YOUR_API_KEY"},
"req_template_json_object": {
"model": "custom-model",
"messages": [{"role": "user", "content": "$INPUT"}]
},
"response_json": true,
"response_json_field": "$.choices[0].message.content"
}'
# Test with proxy interception (Burp Suite, mitmproxy)
augustus scan rest.Rest \
--probes-glob "goodside.*" \
--config '{
"uri": "https://internal-llm.corp/generate",
"proxy": "http://127.0.0.1:8080",
"headers": {"X-API-Key": "$KEY"},
"api_key": "your-key-here",
"req_template": "{\"prompt\":\"$INPUT\",\"max_tokens\":500}",
"response_json": true,
"response_json_field": "output"
}'
```
**Chiavi di configurazione REST:**
- `uri`: endpoint API di destinazione (obbligatorio)
- `method`: metodo HTTP (predefinito: POST)
- `headers`: intestazioni HTTP come coppie chiave-valore
- `req_template`: corpo della richiesta grezzo con segnaposto `$INPUT`
- `req_template_json_object`: corpo della richiesta JSON (serializzato automaticamente, usa `$INPUT` nelle stringhe)
- `response_json`: analizza la risposta come JSON (predefinito: false)
- `response_json_field`: JSONPath da estrarre (ad es., `$.data.text` o un semplice nome di campo)
- `api_key`: chiave API per la sostituzione del segnaposto `$KEY`
- `proxy`: URL del proxy HTTP per l'ispezione del traffico
### Opzioni avanzate```bash
# Adjust concurrency (default: 10)
augustus scan openai.OpenAI --all --concurrency 20
# Increase timeout for complex probes like TAP or PAIR
augustus scan openai.OpenAI --probe tap.TAPv1 --timeout 60m
# Use a specific harness strategy
augustus scan openai.OpenAI --all --harness batch.Batch
# Test local model with Ollama (no API key needed)
augustus scan ollama.OllamaChat \
--probe dan.Dan_11_0 \
--config '{"model":"llama3.2:3b"}'
```
## Come Funziona
Augustus utilizza un'architettura a pipeline per testare gli LLM contro attacchi avversari:```mermaid
flowchart LR
A[Probe Selection] --> B[Buff Transform]
B --> C[Generator / LLM Call]
C --> D[Detector Analysis]
D --> E{Vulnerable?}
E -->|Yes| F[Record Finding]
E -->|No| G[Record Pass]
subgraph Scanner
B
C
D
E
end
```
### Pipeline di Scansione
1. **Selezione delle Probe**: Scegli le probe per nome, pattern glob o `--all`
2. **Trasformazione del Buffer**: Trasforma facoltativamente i prompt (codifica, parafrasi, traduzione, poeticizzazione)
3. **Chiamata al Generatore**: Invia prompt avversariali all'LLM target tramite l'integrazione con il suo provider
4. **Analisi del Rilevatore**: Analizza le risposte usando pattern matching, LLM-as-a-judge o rilevatori specializzati
5. **Registrazione dei Risultati**: Assegna un punteggio a ogni tentativo e produce l'output nel formato richiesto
6. **Motore di Attacco**: Per le probe iterative (PAIR, TAP), il motore di attacco a turno singolo perfeziona i prompt attraverso le iterazioni con potatura dei candidati e punteggio basato sul giudice
7. **Motore Multi-Turno**: Per le probe conversazionali (Crescendo, GOAT), il motore multi-turno mantiene la cronologia completa della conversazione con il target attraverso i turni, con rilevamento dei rifiuti e adattamento dinamico
### Strategie di Attacco Multi-Turno
Gli attacchi multi-turno mantengono una conversazione persistente con l'LLM target, sfruttando il fatto che i modelli possono rivelare informazioni in modo incrementale attraverso i turni che rifiuterebbero in un singolo prompt. Il motore multi-turno utilizza tre LLM: un **attaccante** (genera le domande), un **target** (il sistema sotto test) e un **giudice** (valuta i progressi e rileva i rifiuti).
#### Crescendo
Crescendo utilizza l'escalation graduale (tecnica del piede nella porta) per spostare lentamente una conversazione da argomenti benigni verso un obiettivo proibito.
- **Paper**: [Russinovich et al., 2024](https://arxiv.org/abs/2404.01833)
- **Approccio**: Inizia con domande genuinamente benigne ed educative e aumenta incrementalmente la specificità attraverso molti turni
- **Pattern di escalation**: Contesto storico → meccanismi tecnici → dettagli specifici → richieste dirette presentate come follow-up naturali
- **Punto di forza**: Efficace contro i modelli che tracciano il tono della conversazione — lo spostamento graduale evita di attivare i filtri di sicurezza```bash
augustus scan rest.Rest \
--probe crescendo.Crescendo \
--config-file crescendo.yaml \
--html report.html -v
```
#### GOAT (Generative Offensive Agent Tester)
GOAT utilizza un approccio aggressivo e adattivo con 7 tecniche avversariali e il ragionamento Chain-of-Attack-Thought per cambiare dinamicamente strategia in base a ciò che funziona o fallisce.
- **Paper**: [Pavlova et al., 2024](https://arxiv.org/abs/2410.01606)
- **Approccio**: Punta all'obiettivo fin dal turno 1 usando un framing indiretto, non menziona mai l'obiettivo direttamente al target
- **7 tecniche** in 3 categorie:
- *Output Manipulation*: Refusal Suppression, Response Priming
- *Safe Response Distractors*: Dual Response, Topic Splitting, Opposite Intent
- *Fictional Scenarios*: Persona Modification, Hypothetical
- **Chain-of-Attack-Thought**: A ogni turno l'attaccante ragiona attraverso Observation → Thought → Strategy → Response prima di formulare il suo messaggio
- **Combinazione di tecniche**: Più tecniche possono essere combinate in un singolo turno per un effetto più forte
- **Punto di forza**: Raggiunge alti tassi di successo in meno turni (tipicamente 3-5) passando aggressivamente tra approcci fondamentalmente diversi```bash
augustus scan rest.Rest \
--probe goat.Goat \
--config-file goat.yaml \
--html report.html -v
```
#### Hydra
Hydra mantiene un unico percorso di conversazione e annulla interi turni quando il target rifiuta, chiedendo all'attaccante un approccio completamente diverso. A differenza di Crescendo/GOAT (che riformulano in caso di rifiuto), il backtracking di Hydra rimuove completamente i turni rifiutati dalla visuale del target.
- **Approccio**: Percorso singolo con backtracking a livello di turno — i turni rifiutati vengono cancellati e sostituiti
- **Tecniche**: Decomposizione (scomporre l'obiettivo in sotto-domande innocue), sfruttamento del contesto (basarsi sulle parole del target), simulazione di autorità, inquadramento emotivo, normalizzazione progressiva
- **Caratteristica chiave**: `max_backtracks` controlla quante volte Hydra può cancellare e riprovare un turno
- **Modalità stateful**: Imposta `stateful: true` per i target in cui i messaggi non possono essere annullati (disabilita il backtracking)
- **Punto di forza**: Mantiene pulita la cronologia della conversazione del target — il target non vede mai gli approcci falliti, prevenendo l'escalation difensiva```bash
augustus scan rest.Rest \
--probe hydra.Hydra \
--config-file hydra.yaml \
--html report.html -v
```
#### Utente Malizioso
L'Utente Malizioso simula una persona innocente e curiosa che sonda sottilmente i limiti dell'IA attraverso una conversazione naturale. A differenza delle strategie avversariali, la persona dell'attaccante è un utente occasionale che si sposta verso argomenti proibiti tramite un coinvolgimento apparentemente innocente.
- **Ispirato da**: [Tau-bench](https://github.com/sierra-research/tau-bench) e dalla strategia dell'utente malizioso di promptfoo
- **Approccio**: Fase di costruzione del rapporto → sondaggio dei limiti → spinta assertiva
- **7 tecniche**: Curiosità ingenua, fraintendimento deliberato, prova sociale, deriva graduale, appello emotivo, permesso presunto, ricontestualizzazione
- **Playbook specifici per obiettivo**: Script integrati per estrarre istruzioni di sistema, trovare segreti/flag e bypassare la policy sui contenuti
- **Turni predefiniti**: 5 (meno rispetto ad altre strategie — l'approccio sottile funziona rapidamente o per niente)
- **Punto di forza**: Efficace contro modelli addestrati a resistere a pattern avversariali evidenti — la persona casuale aggira le euristiche di "rilevamento degli attacchi"```bash
augustus scan rest.Rest \
--probe mischievous.MischievousUser \
--config-file mischievous.yaml \
--html report.html -v
```
#### Guida alla Selezione della Strategia
| Strategia | Turni | Stile | Ideale Per | Costo |
|----------|-------|-------|----------|------|
| `crescendo.Crescendo` | 10 | Escalation graduale | Modelli con filtri di sicurezza basati sul tracciamento del tono | Medio (10 turni × 3 chiamate LLM) |
| `goat.Goat` | 10 | Cambio aggressivo di tecnica | Risultati rapidi, modelli deboli contro i trucchi di framing | Medio-Alto (overhead di ragionamento sulle tecniche) |
| `hydra.Hydra` | 10 | Backtracking al rifiuto | Modelli ostinati che rifiutano frequentemente | Alto (il backtracking aggiunge nuovi tentativi) |
| `mischievous.MischievousUser` | 5 | Sondaggio informale della persona | Modelli addestrati contro pattern avversari | Basso (5 turni, approccio sottile) |
**Decisione rapida**:
- Inizia con **Crescendo** — è la strategia più generica
- Prova **GOAT** se Crescendo è troppo lento (GOAT di solito riesce in 3-5 turni)
- Usa **Hydra** se il target rifiuta frequentemente (il backtracking mantiene la conversazione pulita)
- Usa **Mischievous** per target con forte rilevamento di pattern avversari (la persona bypassa le euristiche)
#### Configurazione Multi-Turno
Tutte e quattro le strategie condividono la stessa struttura di configurazione:```yaml
generators:
rest.Rest:
uri: "https://your-llm-endpoint/chat"
method: POST
req_template: '{"input": "$INPUT"}'
response_json: true
response_json_field: "response"
judge:
generator_type: openai.OpenAI
config:
model: gpt-4
api_key: "${OPENAI_API_KEY}"
probes:
attacker_generator_type: openai.OpenAI
attacker_config:
model: gpt-4
api_key: "${OPENAI_API_KEY}"
settings:
crescendo.Crescendo: # or goat.Goat, hydra.Hydra, mischievous.MischievousUser
goal: "your test objective"
max_turns: 10
success_threshold: 0.8
use_secondary_judge: true
```
| Setting | Default | Descrizione |
|---------|---------|-------------|
| `goal` | (obbligatorio) | L'obiettivo che l'attaccante cerca di raggiungere |
| `max_turns` | 10 | Numero massimo di turni di conversazione prima dell'arresto |
| `success_threshold` | 0.8 | Punteggio del giudice (0.0-1.0) che attiva l'uscita anticipata |
| `max_refusal_retries` | 10 | Tentativi di riformulazione per turno quando il target rifiuta |
| `attack_max_attempts` | 5 | Nuovi tentativi per errori di parsing JSON dell'LLM attaccante |
| `use_secondary_judge` | true | Abilita il giudice secondario per rilevare falsi negativi |
| `max_backtracks` | 10 | Rollback a livello di turno in caso di rifiuto (solo Hydra) |
| `enable_fast_refusal` | true | Rilevamento del rifiuto basato su pattern prima della chiamata al giudice LLM |
| `enable_scan_memory` | false | Apprendimento tra casi di test (condivide tattiche tra i probe) |
| `stateful` | false | Disabilita il backtracking per target con stato |
| `exclude_target_output` | false | Nasconde le risposte del target dal feedback dell'attaccante (modalità privacy) |
| `attacker_model` | (auto) | Sovrascrive il nome del modello attaccante per il dimensionamento della finestra di contesto |
#### Risoluzione dei Problemi Multi-Turno
| Sintomo | Causa Probabile | Soluzione |
|---------|-------------|-----|
| `no turns completed (attacker_parse_failures=N)` | L'LLM attaccante restituisce JSON non valido | Usa un modello attaccante più potente (GPT-4, Claude Opus). Aumenta `attack_max_attempts`. |
| `no turns completed (target_empty=N)` | Il target restituisce risposte vuote/null | Verifica che l'endpoint del target risponda. Controlla il template di configurazione REST. |
| Tutti i turni ottengono punteggio 0.0 | Obiettivo troppo vago o attaccante non coinvolto | Rendi `goal` più specifico. Prova una strategia diversa. |
| Punteggi alti ma nessun successo | `success_threshold` troppo alto | Abbassa `success_threshold` da 0.8 a 0.6-0.7 |
| Esecuzioni troppo lunghe/costose | Troppi turni e nuovi tentativi | Riduci `max_turns` (prova 5). Imposta `enable_fast_refusal: true`. |
| Hydra continua a fare backtracking | Il target rifiuta tutto | Prova `stateful: true` o passa alla strategia Mischievous |
## Architettura```
cmd/augustus/ CLI entrypoint (Kong-based)
pkg/
attempt/ Probe execution lifecycle and result tracking
buffs/ Buff interface for prompt transformations
config/ Configuration loading (YAML/JSON) with profiles
detectors/ Public detector interfaces and registry
generators/ Public generator interfaces and registry
harnesses/ Harness interface for execution strategies
lib/http/ Shared HTTP client with proxy support
lib/stego/ LSB steganography for multimodal attacks
logging/ Structured slog-based logging
metrics/ Prometheus metrics collection
prefilter/ Aho-Corasick keyword pre-filtering
probes/ Public probe interfaces and registry
ratelimit/ Token bucket rate limiting
registry/ Generic capability registration system
results/ Result types and multi-format output
retry/ Exponential backoff with jitter
scanner/ Scanner orchestration with concurrency
templates/ YAML probe template loader (Nuclei-style)
types/ Canonical shared interfaces (Prober, Generator, Detector)
internal/
probes/ 210+ probe implementations (47 categories)
generators/ 28 LLM provider integrations (43 variants)
detectors/ 90+ detector implementations (35 categories)
harnesses/ 3 harness strategies (probewise, batch, agentwise)
buffs/ Buff interface for prompt transformations
attackengine/ Iterative adversarial attack engine (PAIR/TAP backend)
multiturn/ Multi-turn conversational attack engine (Crescendo/GOAT/Hydra/Mischievous)
ahocorasick/ Internal Aho-Corasick keyword matching
benchmarks/ Performance benchmarks
tests/ Integration and equivalence tests
research/ Research documentation and analysis
examples/ Example configurations
docs/ Documentation
```
### Decisioni di Progettazione Chiave
- **Scansione concorrente** con pool di goroutine limitati tramite `errgroup`
- **Registrazione in stile plugin** utilizzando le funzioni `init()` di Go per probe, generatori, rilevatori, potenziamenti e harness
- **Motore di attacco iterativo** con gestione di conversazioni multi-stream, potatura dei candidati e punteggio basato su giudice per PAIR/TAP
- **Motore di attacco multi-turno** con cronologia di conversazione persistente, rilevamento dei rifiuti e design agnostico rispetto alla strategia per Crescendo/GOAT
- **Modelli di probe YAML** (in stile Nuclei) per definizioni dichiarative dei probe insieme a probe basati su Go
- **Pre-filtraggio Aho-Corasick** per il rapido matching delle parole chiave nei rilevatori
## Configurazione
### File di Configurazione YAML
Crea un file `config.yaml`:```yaml
# Runtime configuration
run:
max_attempts: 3
timeout: "30s"
# Generator configurations
generators:
openai.OpenAI:
model: "gpt-4"
temperature: 0.7
api_key: "${OPENAI_API_KEY}" # Environment variable interpolation
anthropic.Anthropic:
model: "claude-3-opus-20240229"
temperature: 0.5
api_key: "${ANTHROPIC_API_KEY}"
ollama.OllamaChat:
model: "llama3.2:3b"
temperature: 0.8
# Judge configuration (required for judge.Judge, judge.Refusal, and multi-turn probes)
judge:
generator_type: openai.OpenAI
model: gpt-4o-mini
config:
api_key: "${OPENAI_API_KEY}"
# Output configuration
output:
format: "jsonl"
path: "./results.jsonl"
# Named profiles for different scenarios
profiles:
quick:
run:
max_attempts: 1
timeout: "10s"
generators:
openai.OpenAI:
model: "gpt-3.5-turbo"
temperature: 0.5
output:
format: "table"
thorough:
run:
max_attempts: 5
timeout: "60s"
generators:
openai.OpenAI:
model: "gpt-4"
temperature: 0.3
output:
format: "jsonl"
path: "./thorough_results.jsonl"
```
### Variabili d'ambiente```bash
# API Keys
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export COHERE_API_KEY="..."
# Debug mode
export AUGUSTUS_DEBUG=true
```
### Configurazione del Proxy
Instrada il traffico HTTP attraverso un proxy (ad es. Burp Suite) per l'ispezione:```bash
# Method 1: Via config parameter
augustus scan rest.Rest \
--probe dan.Dan_11_0 \
--detector dan.DAN \
--config '{"uri":"https://api.example.com","proxy":"http://127.0.0.1:8080"}' \
--output results.jsonl
# Method 2: Via environment variables
export HTTP_PROXY=http://127.0.0.1:8080
export HTTPS_PROXY=http://127.0.0.1:8080
augustus scan rest.Rest --probe dan.Dan_11_0 --config '{"uri":"https://api.example.com"}'
```
- Verifica TLS automaticamente disabilitata per l'ispezione del proxy
- Supporto HTTP/2 abilitato per API moderne
- Risposte Server-Sent Events (SSE) rilevate e analizzate automaticamente
### Riferimento CLI```
Usage: augustus scan <generator> [flags]
Arguments:
<generator> Generator name (e.g., openai.OpenAI, anthropic.Anthropic)
Probe Selection (choose one):
--probe, -p Probe name (repeatable)
--probes-glob Comma-separated glob patterns (e.g., "dan.*,goodside.*")
--all Run all registered probes
Detector Selection:
--detector Detector name (repeatable)
--detectors-glob Comma-separated glob patterns
Buff Selection:
--buff, -b Buff names to apply (repeatable)
--buffs-glob Comma-separated buff glob patterns (e.g., "encoding.*")
Configuration:
--config-file Path to YAML config file
--config, -c JSON config for generator
Execution:
--harness Harness name (default: probewise.Probewise)
--timeout Overall scan timeout (default: 30m)
--probe-timeout Per-probe timeout (default: 5m)
--concurrency Max concurrent probes (default: 10, env: AUGUSTUS_CONCURRENCY)
Output:
--format, -f Output format: table, json, jsonl (default: table)
--output, -o JSONL output file path
--html HTML report file path
--verbose, -v Verbose output
Global:
--debug, -d Enable debug mode
```
**Comandi:**```bash
augustus version # Print version information
augustus list # List available probes, detectors, generators, harnesses, buffs
augustus scan <generator> # Run vulnerability scan
augustus completion <shell> # Generate shell completion (bash, zsh, fish)
```
**Codici di uscita:**
| Codice | Significato |
|------|---------|
| 0 | Successo - scansione completata |
| 1 | Errore di scansione/runtime |
| 2 | Errore di validazione/utilizzo |
## FAQ
### Come si confronta Augustus con garak?
Augustus è una reimplementazione nativa in Go ispirata a [garak](https://github.com/NVIDIA/garak) (lo scanner di vulnerabilità LLM basato su Python di NVIDIA). Differenze principali:
- **Prestazioni**: binario Go vs interprete Python — esecuzione più rapida e minore utilizzo di memoria
- **Distribuzione**: singolo binario senza dipendenze runtime vs pacchetto Python con installazione tramite pip
- **Concorrenza**: pool di goroutine Go (parallelismo tra probe) vs pool di multiprocessing Python (parallelismo all'interno dei probe)
- **Copertura dei probe**: Augustus ha oltre 210 probe; garak ha oltre 160 probe con un pedigree di ricerca più lungo e un articolo pubblicato (arXiv:2406.11036)
- **Copertura dei provider**: Augustus ha 28 provider; garak ha oltre 35 varianti di generatori su 22 moduli provider
### Posso testare modelli locali senza chiavi API?
Sì! Usa l'integrazione Ollama per il test di modelli locali:```bash
# No API key needed
augustus scan ollama.OllamaChat \
--probe dan.Dan_11_0 \
--config '{"model":"llama3.2:3b"}'
```
### Come aggiungo probe personalizzate?
1. Crea un nuovo file Go in `internal/probes/`
2. Implementa l'interfaccia `probes.Probe`
3. Registrala usando `registry.RegisterProbe()` in una funzione `init()`
4. Ricompila: `make build`
Consulta [CONTRIBUTING.md](https://github.com/praetorian-inc/augustus/blob/main/CONTRIBUTING.md) per istruzioni dettagliate.
### Quali formati di output sono supportati?
Augustus supporta quattro formati di output:
| Formato | Flag | Caso d'uso |
|--------|------|----------|
| Tabella | `--format table` | Output leggibile per il terminale |
| JSON | `--format json` | Singolo oggetto JSON per il parsing |
| JSONL | `--format jsonl` | JSON delimitato da righe per lo streaming |
| HTML | `--html report.html` | Report visivi per gli stakeholder |
### Come posso testare più modelli contemporaneamente?```bash
# Test multiple models sequentially
for model in "gpt-4" "gpt-3.5-turbo"; do
augustus scan openai.OpenAI \
--all \
--config "{\"model\":\"$model\"}" \
--output "results-$model.jsonl"
done
```
### Augustus è adatto per ambienti di produzione?
Sì, Augustus è progettato per l'uso in produzione con:
- Scansione concorrente con limiti configurabili
- Limitazione della velocità per rispettare le quote API
- Gestione dei timeout per probe di lunga durata
- Logica di retry per guasti transitori
- Logging strutturato per l'osservabilità
## Risoluzione dei problemi
### Errore: "Limite di velocità API superato"
**Causa**: Troppe richieste concorrenti o troppe richieste al minuto.
**Soluzioni**:
1. Riduci la concorrenza: `--concurrency 5`
2. Utilizza le impostazioni di limitazione della velocità specifiche del provider nella configurazione YAML: ```yaml
generators:
openai.OpenAI:
rate_limit: 10 # requests per minute
```
### Errore: "context deadline exceeded" o "timeout"
**Causa**: Sonde complesse (come TAP o PAIR) superano il timeout predefinito.
**Soluzione**:```bash
augustus scan openai.OpenAI \
--probe tap.TAPv1 \
--timeout 60m \
--config-file config.yaml
```
### Errore: "invalid API key" o "authentication failed"
**Causa**: Credenziali API mancanti o non valide.
**Soluzioni**:
1. Verifica che la variabile d'ambiente sia impostata: `echo $OPENAI_API_KEY`
2. Controlla eventuali errori di battitura nel file di configurazione
3. Assicurati che la chiave API abbia i permessi richiesti
4. Per Ollama, assicurati che il servizio sia in esecuzione: `ollama serve`
### Errore: "probe not found" o "detector not found"
**Causa**: Errore di battitura nel nome o probe non registrato.
**Soluzione**:```bash
# List all available probes and detectors
augustus list
# Use exact names from the list
augustus scan openai.OpenAI --probe dan.Dan_11_0 # Correct
```
### La scansione non produce risultati
**Causa**: Il detector non ha trovato corrispondenze nelle risposte, oppure l'output non è stato scritto.
**Soluzioni**:
1. Esegui con `--verbose` per vedere l'output dettagliato
2. Verifica che il detector corrisponda al tipo di probe
3. Controlla che il percorso del file di output sia scrivibile
## Contribuire
Accogliamo con piacere i contributi! Vedi [CONTRIBUTING.md](https://github.com/praetorian-inc/augustus/blob/main/CONTRIBUTING.md) per:
- Aggiungere nuovi probe di vulnerabilità
- Creare nuove implementazioni di detector
- Aggiungere integrazioni con provider LLM
- Linee guida per i test
- Requisiti di stile del codice
### Sviluppo```bash
# Run all tests
make test
# Run specific package tests
go test ./pkg/scanner -v
# Run equivalence tests (compare Go vs Python implementations)
go test ./tests/equivalence -v
# Build binary
make build
# Install to $GOPATH/bin
make install
```
### Ambiente di Benchmark (DevPod)
Un ambiente di sviluppo cloud pronto all'uso per il benchmarking degli LLM è disponibile tramite [DevPod](https://devpod.sh/). Esso fornisce un container remoto con Augustus, Ollama, Go e tutte le dipendenze preinstallate.```bash
cd devpod
# CPU-only instance (~$0.08/hr) - cloud APIs only
make devpod-up-cpu
# GPU instance with NVIDIA T4 (~$0.53/hr) - local models up to 14B
make devpod-up-gpu
# GPU Pro instance with NVIDIA L4 (~$0.80/hr) - local models up to 32B
make devpod-up-gpu-pro
```
Dentro del devpod:```bash
devpod/scripts/setup.sh # Configure LLM provider API keys
devpod/scripts/pull-models.sh # Pull local Ollama models (GPU only)
devpod/scripts/benchmark.sh # Run benchmarks with comparison reports
```
L'ambiente funziona anche come un [dev container](https://containers.dev/) standard: apri il repository in VS Code o Cursor e seleziona la configurazione CPU o GPU da `.devcontainer/`.
## Sicurezza
Augustus è progettato **esclusivamente per test di sicurezza autorizzati**.
- Augustus invia prompt avversari agli LLM che specifichi: assicurati sempre di avere l'autorizzazione
- Non testare mai sistemi che non possiedi o per cui non hai un permesso esplicito
- Alcune sonde generano contenuti offensivi di proposito (per testare i filtri di sicurezza)
- I risultati possono contenere contenuti dannosi prodotti dagli LLM target
Segnala problemi di sicurezza tramite [GitHub Issues](https://github.com/praetorian-inc/augustus/issues).
## Supporto
Se trovi Augustus utile, considera:
- Dargli una **stella** su GitHub
- [Aprire un issue](https://github.com/praetorian-inc/augustus/issues) per bug o richieste di funzionalità
- [Contribuire](https://github.com/praetorian-inc/augustus/blob/main/CONTRIBUTING.md) con nuove sonde, rilevatori o integrazioni di provider
[](https://star-history.com/#praetorian-inc/augustus&Date)
## Licenza
[Apache 2.0](https://github.com/praetorian-inc/augustus/blob/main/LICENSE) - Praetorian Security, Inc.
---
**Creato da [Praetorian](https://www.praetorian.com/)** - Soluzioni di Sicurezza Offensiva