Titus: Scanner di Segreti ad Alte Prestazioni

Titus è uno scanner di segreti ad alte prestazioni che rileva credenziali, chiavi API e token in codice sorgente, file e cronologia git. Include 487 regole di rilevamento che coprono centinaia di servizi e tipi di credenziali, tratte da NoseyParker e Kingfisher. Titus funziona come CLI, libreria Go, estensione per Burp Suite ed estensione per browser Chrome — tutte condividono lo stesso motore di rilevamento e lo stesso set di regole.

Progettato per ingegneri della sicurezza, penetration tester e team DevSecOps, Titus combina il matching regex accelerato da Hyperscan/Vectorscan con la validazione delle credenziali in tempo reale per trovare e verificare i segreti trapelati in tutto il tuo codebase.

Indice

• Perché Titus?
• Installazione
• Avvio Rapido
• Opzioni di Scansione
• Punteggio dei Risultati
• Libreria Go
• Estensione per Burp Suite
• Estensione per Browser
• Compilazione dal Sorgente
• Contribuire
• Licenza

Perché Titus?

• Scansione dei segreti veloce: matching regex accelerato da Hyperscan/Vectorscan quando disponibile, con un fallback in puro Go per la portabilità su qualsiasi piattaforma.
• Ampia copertura nel rilevamento delle credenziali: 487 regole rilevano chiavi API, token e credenziali per AWS, GCP, Azure, GitHub, Slack, database, sistemi CI/CD e centinaia di altri servizi.
• Validazione dei segreti in tempo reale: i segreti rilevati vengono verificati rispetto alle loro API di origine per confermare se sono attivi, riducendo i falsi positivi e dando priorità alla remediation.
• Punteggio di severità basato sul rischio: ogni risultato riceve un punteggio numerico (0–100) e un livello di severità (info → critical). I punteggi sono calibrati tramite metadati statici delle regole, contesto di accessibilità al codice e chiamate API in tempo reale che misurano il reale raggio d'impatto di una credenziale — così i risultati più pericolosi emergono sempre per primi.
• Scansione di immagini container: scansiona immagini Docker e OCI direttamente da qualsiasi registry, tarball o directory di layout OCI — senza bisogno del daemon o del binario Docker.
• Interfacce multiple per ogni flusso di lavoro: scansiona dalla CLI, integra come libreria Go, scansiona passivamente il traffico HTTP in Burp Suite o scansiona pagine web in Chrome durante i test di sicurezza delle applicazioni.
• Estrazione da file binari: estrai e scansiona segreti da documenti Office, PDF, archivi (zip, tar, 7z), app mobile (APK, IPA), estensioni per browser e altro ancora.

Installazione

Scarica un binario precompilato dalla pagina Releases oppure compila dal sorgente:```bash make build

Il binario sarà in `dist/titus`.

## Avvio rapido```bash
# Scan a file for secrets
titus scan path/to/file.txt

# Scan a directory for leaked credentials
titus scan path/to/directory

# Scan a public GitHub repository (no token needed)
titus scan github.com/org/repo

# Scan a public GitLab project (no token needed)
titus scan gitlab.com/namespace/project

# Scan git history for secrets in past commits
titus scan --git path/to/repo

# Scan a Docker / OCI image (pulled from a registry — no docker daemon required)
titus scan --docker alpine:latest

# Validate detected secrets against source APIs
titus scan path/to/code --validate

I risultati vengono scritti in un datastore (titus.ds per impostazione predefinita) e stampati sulla console.

Opzioni di scansione

Scansione di GitHub e GitLab

Scansiona i repository pubblici direttamente tramite URL — nessun token API richiesto:```bash

Scan a GitHub repository

titus scan github.com/kubernetes/kubernetes

Scan a GitLab project

titus scan gitlab.com/gitlab-org/cli

Full URLs work too

titus scan https://github.com/org/repo titus scan https://gitlab.com/namespace/project.git

Per la scansione a livello di organizzazione o di utente, utilizzare i sottocomandi dedicati:```bash
# Scan all public repos in a GitHub org
titus github --org kubernetes

# Scan all repos in a GitHub org with a token (private repos + higher rate limits)
titus github --org kubernetes --token $GITHUB_TOKEN

# Scan all repos for a GitHub user
titus github --user octocat

# Scan all projects in a GitLab group
titus gitlab scan --group mygroup --token $GITLAB_TOKEN

# Scan a single repo with git history (finds deleted secrets)
titus github owner/repo --git

I token sono opzionali per i repository pubblici. Imposta GITHUB_TOKEN o GITLAB_TOKEN (oppure usa --token) per l'accesso ai repository privati e limiti API più elevati.

Scansione di immagini Docker / OCI

Scansiona direttamente le immagini dei container — nessun daemon docker, nessun binario docker richiesto. Titus estrae le immagini direttamente da qualsiasi registry OCI tramite HTTPS (usando le credenziali da ~/.docker/config.json), oppure legge le immagini da un tarball locale docker save o da una directory di layout di immagini OCI. Successivamente scansiona i metadati del manifest/config dell'immagine e ogni file regolare in ogni layer, inclusi i file dei layer inferiori eliminati dai layer successivi (poiché i segreti possono rimanere recuperabili dalla cronologia dell'immagine).```bash

Pull from a registry and scan

titus scan --docker alpine:latest titus scan docker://ghcr.io/owner/repo:tag

Scan an image saved to a tarball:

docker save my-app:latest -o my-app.tar

podman save my-app:latest -o my-app.tar

titus scan --docker ./my-app.tar

Scan an OCI image layout directory:

docker buildx build --output type=oci,dest=./img/ .

skopeo copy docker://my-app:latest oci:./img:latest

titus scan --docker ./img/

L'autenticazione utilizza la tua configurazione Docker / Podman esistente (`~/.docker/config.json`, `${XDG_RUNTIME_DIR}/containers/auth.json`). I registry privati che richiedono un nuovo login devono prima essere autenticati con `docker login` (o `podman login`, o `crane auth login`) — titus non richiede le credenziali.

### Visualizzazione dei Risultati della Scansione

Usa `report` per rileggere i risultati di una scansione precedente:```bash
# Human-readable summary of detected secrets
titus report

# JSON output for programmatic processing
titus report --format json

# SARIF output for CI/CD integration with GitHub Advanced Security
titus report --format sarif

# Report from a specific datastore
titus report --datastore path/to/titus.ds

Puoi anche controllare il formato di output al momento della scansione con --format:```bash titus scan path/to/code --format json

### Convalida dei Segreti Rilevati

Passa `--validate` durante una scansione per verificare i segreti rilevati rispetto alle loro API di origine:```bash
titus scan path/to/code --validate

La validazione viene eseguita in modo concorrente (4 worker per impostazione predefinita, configurabile con --validate-workers) e contrassegna ogni risultato come confermato, negato o sconosciuto.

Regole di rilevamento del filtraggio```bash

List all available detection rules

titus rules list

Scan with only specific rules (e.g., AWS and GCP credentials)

titus scan path/to/code --rules-include "aws,gcp"

Exclude rules by pattern

titus scan path/to/code --rules-exclude "kingfisher.generic"

Use a custom rules file for organization-specific secrets

titus scan path/to/code --rules path/to/custom-rules.yaml

Opt in to rules marked noisy: true (high false-positive rate, off by default)

titus scan path/to/code --include-noisy

### Estrazione di segreti da file binari

Titus può estrarre testo da formati di file binari e scansionare il contenuto alla ricerca di segreti:```bash
# Extract and scan all supported binary formats
titus scan path/to/files --extract=all

# Target specific formats
titus scan path/to/files --extract=xlsx,docx,pdf,zip

I formati supportati includono documenti Office (xlsx, docx, pptx, odp, ods, odt), PDF, notebook Jupyter, database SQLite, email (eml, rtf) e archivi (zip, tar, tar.gz, jar, war, ear, apk, ipa, crx, xpi, 7z). Gli archivi vengono estratti ricorsivamente fino a profondità e limiti di dimensione configurabili.```bash

Tune extraction limits for large codebases

titus scan path/to/files --extract=all
--extract-max-size 10MB
--extract-max-total 100MB
--extract-max-depth 5

Per i database SQLite, Titus estrae il testo da tutte le tabelle (1000 righe per tabella per impostazione predefinita). Usa `--sqlite-row-limit` per modificare:```bash
# Full dump of all SQLite tables (no row limit)
titus scan path/to/files --extract=all --sqlite-row-limit 0

# Custom row limit per table
titus scan path/to/files --extract=all --sqlite-row-limit 5000

Assegnazione del punteggio ai finding

Ogni finding prodotto da Titus porta con sé un punteggio numerico da 0 a 100 e un livello di gravità:

I punteggi partono dal base_score della regola e vengono modificati dai modificatori — condizioni che aumentano o diminuiscono il punteggio in base a ciò che è noto sulla credenziale:```bash

Score findings using static rule metadata only (no network calls)

titus scan path/to/code

Score findings AND make live API calls to verify credential blast radius

(calls AWS STS/IAM and GitHub API for supported credential types)

titus scan path/to/code --score-scope

Override the accessibility context (default: auto-detected from git remote)

titus scan path/to/code --accessibility public # no penalty for public repos titus scan path/to/code --accessibility private # -25 penalty (default for local scans)

Titus include scorer YAML per le credenziali AWS, i PAT di GitHub e i token Slack, oltre a scorer SDK basati su Go che eseguono l'enumerazione live delle policy IAM (AWS) e i controlli dei permessi dei repository (PAT fine-grained di GitHub) quando `--score-scope` è abilitato.

Consulta [docs/scoring.md](https://github.com/praetorian-inc/titus/blob/main/docs/scoring.md) per il riferimento completo: livelli di severità, tipi di modificatori, dettagli sugli scorer integrati e come scrivere i tuoi scorer YAML o Go.

## Libreria Go per il rilevamento dei segreti

Titus può essere importato come libreria Go per aggiungere il rilevamento dei segreti ai tuoi strumenti e pipeline.```bash
go get github.com/praetorian-inc/titus

I cannot translate this content because no text was provided. The INPUT section is empty.

Please send the actual Markdown content for chunk 29, and I will translate it into Italian following all the rules you specified.```go package main

import ( "fmt" "log"

"github.com/praetorian-inc/titus"

)

func main() { // Initialize the secrets scanner with default rules scanner, err := titus.NewScanner() if err != nil { log.Fatal(err) } defer scanner.Close()

// Scan a string for API keys, tokens, and credentials
matches, err := scanner.ScanString(`aws_access_key_id = AKIAIOSFODNN7EXAMPLE`)
if err != nil {
    log.Fatal(err)
}

for _, match := range matches {
    fmt.Printf("%s (rule: %s) at line %d\n",
        match.RuleName, match.RuleID,
        match.Location.SourceSpan.Start.Line,
    )
}

}

La libreria supporta anche la scansione di byte e file, la validazione dei segreti rilevati e il caricamento di regole personalizzate:```go
// Scan a file for leaked credentials
matches, err := scanner.ScanFile("/path/to/config.json")

// Enable validation to check if detected secrets are live
scanner, err := titus.NewScanner(titus.WithValidation())

// Load custom detection rules for organization-specific secrets
rules, err := titus.LoadRulesFromFile("/path/to/rules.yaml")
scanner, err := titus.NewScanner(titus.WithRules(rules))

Consulta docs/library-usage.md per il riferimento completo dell'API, i pattern di concorrenza e ulteriori esempi.

Estensione Burp Suite per la scansione dei segreti

L'estensione Burp analizza le risposte HTTP alla ricerca di segreti durante il traffico proxy e i test di penetrazione attivi.

Configurazione

Linux / macOS (compilazione dal sorgente)```bash

Build the CLI and Burp extension JAR, install CLI to ~/.titus/

make install-burp

Poi carica `dist/titus-burp-1.0.0-all.jar` in Burp Suite sotto Extensions > Add.

#### Windows (Download from Releases)

1. Scarica `titus-windows-amd64.exe` e `titus-burp-<version>.jar` da [Releases](../../releases)
2. Crea la directory di Titus e installa il binario:   ```powershell
   mkdir %USERPROFILE%\.titus
   copy titus-windows-amd64.exe %USERPROFILE%\.titus\titus.exe

3. Carica il JAR in Burp Suite sotto Extensions > Add

Linux / macOS (Scarica dalle Releases)

1. Scarica il binario appropriato per la tua piattaforma e titus-burp-<version>.jar da Releases:
   • titus-linux-amd64 o titus-linux-arm64 per Linux
   • titus-darwin-amd64 o titus-darwin-arm64 per macOS
2. Installa il binario: ```bash mkdir -p ~/.titus cp titus- ~/.titus/titus chmod +x ~/.titus/titus
   root@kitploit:~

3. Carica il JAR in Burp Suite sotto Extensions > Add

L'estensione avvia un processo titus serve in background e comunica tramite stdin/stdout usando NDJSON. Le regole di rilevamento vengono caricate una sola volta all'avvio.

Funzionalità dell'estensione Burp

• Scansione passiva dei segreti: scansiona automaticamente il traffico proxy mentre fluisce attraverso Burp
• Scansione attiva dei segreti: menu contestuale con clic destro per scansionare le richieste selezionate
• Deduplicazione: lo stesso segreto viene segnalato una sola volta per engagement
• Filtro fast-path: contenuti binari, immagini e risposte non testuali vengono saltati
• Validazione delle credenziali in tempo reale: verifica i segreti rilevati rispetto alle API di origine per confermare se sono attivi
• Gestione dei falsi positivi: contrassegna i risultati come falsi positivi per filtrare il rumore
• Classificazione della gravità: risultati codificati a colori in base al rischio (Alto/Medio/Basso)
• Esportazione: salva i risultati in JSON per il reporting

Interfaccia dell'estensione Burp

L'estensione aggiunge una scheda Titus a Burp con tre sotto-schede:

Secrets: Tutti i segreti rilevati con filtri per tipo, host e stato di validazione.

Titus Burp Suite extension secrets tab showing detected API keys and credentials with validation status

• Stato di validazione: Mostra se i segreti sono stati verificati (Attivo/Inattivo/Sconosciuto)
• Filtro: Clicca sui pulsanti Type, Host o Status per filtrare in base a valori specifici; usa la casella di ricerca per la corrispondenza di testo e regex
• Azioni in blocco: Seleziona più righe per validare o contrassegnare come falso positivo in batch
• Pannello Secret Details: Seleziona un risultato per visualizzare:
  • Details: Informazioni sulla regola, categoria, valore completo del segreto, timestamp di prima rilevazione
  • URLs: Tutte le posizioni in cui è stato trovato questo segreto
  • Validation: Risultato della validazione con dettagli (es. AWS account ID, ARN)
  • Request/Response: Traffico HTTP completo con il segreto evidenziato

Statistics: Vista aggregata dei segreti raggruppati per tipo e host.

• Summary: Totale segreti unici, host scansionati, riepilogo della validazione (attivi vs inattivi) e conteggio dei falsi positivi
• Secrets by Type: Conteggio di ciascun tipo di segreto con classificazione per categoria
• Secrets by Host: Numero di segreti trovati per host

Settings: Configura le opzioni di scansione, la validazione e le mappature di gravità.

Titus Burp Suite extension settings tab with scan configuration options

• Scan Settings:
  • Scansione passiva: Scansiona automaticamente tutto il traffico proxy (abilitata per impostazione predefinita)
  • Scansione del corpo della richiesta: Scansiona anche i corpi delle richieste per i segreti inviati dall'applicazione
  • Validation: Abilita per verificare i segreti rispetto alle API di origine (effettua richieste in uscita e potrebbe attivare avvisi)
• Scan Parameters: Thread worker, dimensione massima del file, lunghezza dello snippet di contesto
• Severity Configuration: Personalizza i livelli di gravità per categoria di segreto
• Actions: Cancella cache, ripristina impostazioni, salva/esporta i risultati in JSON

Quando si visualizza qualsiasi richiesta in Burp, una scheda Titus appare nell'ispettore delle risposte se vengono rilevati segreti, fornendo un accesso rapido ai risultati senza passare alla scheda principale Titus.

Titus tab in Burp Suite response inspector highlighting detected secrets in HTTP responses

Estensione per browser Chrome per la scansione dei segreti

L'estensione Chrome scansiona le pagine web alla ricerca di segreti durante le valutazioni di sicurezza delle applicazioni web.

Setup```bash

make build-extension

1. Vai su `chrome://extensions/`
2. Abilita la **Modalità sviluppatore**
3. Fai clic su **Carica estensione non pacchettizzata** e seleziona la directory `extension/`

### Funzionalità dell'estensione per browser

- Analizza JavaScript e fogli di stile inline ed esterni alla ricerca di chiavi API e token
- Analizza localStorage e sessionStorage alla ricerca di credenziali trapelate
- Acquisizione opzionale delle risposte di rete per una rilevazione completa dei segreti
- Risultati visualizzati nel popup e nella dashboard

<img width="1719" height="958" alt="Popup dell'estensione Chrome di Titus che mostra i segreti rilevati su una pagina web" src="https://assets.kitploit.com/production/public/readmes/11969/057a24e2746412ceabe1aac0292a2de463de1efee5bca2489ca34b59d8b0dc2c.png" />

<img width="1744" height="827" alt="Dashboard dell'estensione Chrome di Titus con i risultati aggregati della rilevazione dei segreti" src="https://assets.kitploit.com/production/public/readmes/11969/265d972fadcc7f212944d7a1d8fd58a43446e7199d1209900e83b96a546ffb00.png" />

### Avviso di sicurezza

L'estensione per browser rimuove l'Content Security Policy e gli header CORS dalle pagine visitate per analizzare le risorse esterne. Ciò indebolisce la postura di sicurezza dei siti che visiti mentre l'estensione è attiva. **Abilitala solo durante test di sicurezza attivi.**

## Compilazione dal sorgente

### Build standard (accelerata con Vectorscan)

Per impostazione predefinita Titus viene compilato con [Vectorscan](https://github.com/VectorCamp/vectorscan) (ARM) / [Hyperscan](https://github.com/intel/hyperscan) (x86) per il matching regex accelerato con SIMD. Ciò richiede CGO, la libreria C e `pkg-config` (che cgo utilizza per individuare la libreria). `make build` verifica la presenza di questi elementi e tenta di installare ciò che manca tramite Homebrew / apt / dnf:```bash
# Build the CLI binary with vectorscan acceleration (outputs to dist/titus)
make build

# Build the Burp Suite extension JAR
make build-burp

# Build the Chrome browser extension
make build-extension

# Run unit tests
make test

# Run integration tests
make integration-test

Vedrai [vectorscan] N/N rules compiled for Hyperscan all'avvio quando il motore accelerato è attivo.

Per installare tu stesso la libreria C invece di affidarti all'installazione automatica:```bash

macOS (Homebrew)

brew install pkg-config vectorscan

Ubuntu/Debian

sudo apt-get install pkg-config libhyperscan-dev

Fedora/RHEL

sudo dnf install pkgconf-pkg-config vectorscan-devel

Or build vectorscan from source:

git clone --depth 1 --branch vectorscan/5.4.11 https://github.com/VectorCamp/vectorscan.git cd vectorscan && cmake -B build -DCMAKE_INSTALL_PREFIX=/usr/local && cmake --build build && sudo cmake --install build

Se si invoca `go build` direttamente (ad esempio, quando si incorpora Titus), passare il tag e abilitare CGO:```bash
# macOS (Homebrew) — adjust PKG_CONFIG_PATH to your installed version
CGO_ENABLED=1 PKG_CONFIG_PATH="$(brew --prefix vectorscan)/lib/pkgconfig" \
  go build -tags vectorscan -o dist/titus ./cmd/titus

# Linux (system-installed)
CGO_ENABLED=1 go build -tags vectorscan -o dist/titus ./cmd/titus

Build Pure-Go (senza dipendenze C)

Se non puoi installare la libreria C — o desideri un binario completamente portabile e statico — compila invece il motore pure-Go. Titus vi ricorre automaticamente in fase di esecuzione ogni volta che vectorscan non è compilato:```bash

Portable pure-Go binary (no CGO, no vectorscan)

make build-pure

Fully static binary

make build-static

#### Cache automatica del database Hyperscan

Titus serializza automaticamente ogni database Hyperscan compilato con successo
nella cache utente standard. Le istanze successive dello scanner con le stesse
regole ordinate e gli stessi flag caricano quel database invece di compilarlo di nuovo. Il file di cache
è il flusso di byte non modificato prodotto da `hs_serialize_database` di Hyperscan,
e Titus lo carica con `hs_deserialize_database`.

`TITUS_CACHE_DIR` può sovrascrivere la posizione della cache. Le scritture nella cache sono atomiche e
best-effort: una cache non disponibile o di sola lettura non impedisce la scansione. Un database
mancante, corrotto, incompatibile o con fingerprint diverso attiva la
compilazione normale e aggiorna la cache quando possibile.

I database serializzati sono specifici per architettura, funzionalità della CPU e versione di
Hyperscan. Titus rileva le voci incompatibili durante la deserializzazione e le sostituisce
con un database compilato per il runtime corrente.

## Contributing

I contributi sono benvenuti! Consulta [CONTRIBUTING.md](https://github.com/praetorian-inc/titus/blob/main/CONTRIBUTING.md) per le linee guida su come contribuire a Titus.

## License

Apache License 2.0 — vedi [LICENSE](https://github.com/praetorian-inc/titus/blob/main/LICENSE).

Le regole di rilevamento derivano da [NoseyParker](https://github.com/praetorian-inc/noseyparker) (Praetorian Security, Inc.) e [Kingfisher](https://github.com/mongodb/kingfisher) (MongoDB, Inc.), entrambi con licenza Apache 2.0. Vedi [NOTICE](https://github.com/praetorian-inc/titus/blob/main/NOTICE) per l'attribuzione completa.