Skip to content

Piano Definitivo di Implementazione per Ottimizzazione Token

Obiettivo

Ridurre in modo sostanziale il consumo token del progetto senza degradare:

  • copertura della superficie di attacco
  • numero di finding trovati
  • qualita' del reasoning e della verification
  • qualita' del chaining e della prioritizzazione
  • qualita' delle evidenze

Questo piano incorpora:

  • la diagnosi iniziale
  • il piano operativo precedente
  • la review di Opus High
  • la review finale sul piano di handoff

Il principio guida resta uno solo: non rendere il pentest piu' corto, ma eliminare costo statico, costo duplicato, orchestration difettosa e retry inutili prima, attorno e tra i momenti in cui il modello fa lavoro ad alto valore.

Vincoli Non Negoziabili

  1. Nessuna ottimizzazione puo' ridurre findings o coverage senza parity dimostrata.
  2. Nessun downgrade di modello nelle fasi critiche del pentest.
  3. Ogni fase deve essere isolabile, misurabile, rollbackabile.
  4. Ogni fase deve avere acceptance criteria e stop gate espliciti.
  5. Le ottimizzazioni ad alto rischio metodologico restano in shadow mode fino a prova contraria.

Ordine Finale di Rollout

Step 0: Search Hygiene

Implementazione immediata, rischio nullo.

Step 1: Misurazione + Loop Hardening

Prima si misura, poi si blocca il burn inutile.

Step 2: Boilerplate Split + Turn Budgeting

Prima si riduce il costo base comune, poi si chiudono i budget troppo larghi.

Step 3: test-injection POC + Dispatch Compaction

La prima decomposizione skill va fatta insieme al refactor del dispatch per evitare che il dispatcher resti il nuovo collo di bottiglia.

Step 4: Proxy Novelty Gate + Differential Rediscovery

Ottimizzazioni ad alto ROI ma da attivare solo dopo il cleanup del costo statico.

Step 5: Decomposizione altre skill pesanti + orchestratore pentest

Solo dopo che il pattern e' dimostrato con la POC.

Step 6: Lane B opzionale in shadow

Routing piu' aggressivo solo dopo parity chiara delle fasi precedenti.

Mappa Finale delle Flag

Per evitare complessita' combinatoria inutile, le flag vengono consolidate.

  • SEARCH_HYGIENE=1
  • CLAUDE_METRICS=1
  • BB_LOOP_HARDENING=1
  • SKILL_BOILERPLATE_SPLIT=1
  • SKILL_MAX_TURNS_BUDGETING=1
  • TEST_INJECTION_SPLIT=1
  • PROXY_NOVELTY_GATE=1
  • DIFFERENTIAL_REDISCOVERY=1
  • DISPATCH_COMPACTION=1
  • PHASE_SPECIFIC_PENTEST_LOADING=1
  • LANE_B_SHADOW=1

Note:

  • BB_LOOP_HARDENING comprende singleton lock, cooldown globale, dead-run classifier e runtime log separation.
  • TEST_INJECTION_SPLIT implica sempre cross-type signal forwarding.
  • SKILL_BOILERPLATE_SPLIT implica sempre lazy-load dei moduli opzionali.

Step 0: Search Hygiene

Obiettivo

Ridurre context pollution e search noise prima di qualsiasi altra modifica.

File da creare o toccare

Implementazione esatta

Creare .rgignore con almeno queste esclusioni:

  • .claude/worktrees/
  • node_modules/
  • payloads/
  • bugbounty/.runtime/
  • engagements/*/runtime/
  • dashboard/runner/sessions/
  • *.log
  • *.jsonl
  • *.bak.*
  • __pycache__/

Creare .claudeignore con lo stesso set piu':

  • ingest/data/
  • bugbounty/latest-program-changes.json

Acceptance Criteria

  • rg non attraversa piu' worktrees e runtime dirs.
  • I file di runtime non finiscono piu' nel contesto esplorativo per errore.

Rollback

Eliminare i due file.

Step 1A: Metriche e Osservabilita'

Obiettivo

Sapere con numeri dove vengono spesi token, turni e bootstrap statico.

File da toccare

Implementazione esatta

1A.1 Writer JSONL unico

Creare un helper Python riusabile che espone:

  • start_invocation(...) -> run_id
  • finish_invocation(run_id, ...)
  • classify_invocation(...)
  • estimate_prompt_tokens(chars)

Path output:

  • bugbounty/.runtime/metrics/claude-invocations.jsonl
  • engagements/<name>/runtime/claude-invocations.jsonl
  • dashboard/data/runtime/proxy-analysis-metrics.jsonl

1A.2 Schema JSONL obbligatorio

Ogni record deve contenere almeno:

{
  "run_id": "uuid",
  "started_at": "ISO8601",
  "ended_at": "ISO8601",
  "family": "bb-loop|bb-hunt|pentest|proxy-analyzer|runner|knowledge-refresh",
  "caller_file": "path",
  "engagement": "name-or-null",
  "target": "url-or-program",
  "prompt_source": "inline|file",
  "prompt_digest": "sha256",
  "prompt_chars": 12345,
  "estimated_prompt_tokens": 3086,
  "supporting_files_count": 8,
  "supporting_files_bytes": 148221,
  "model": "claude-opus-4-6",
  "max_turns": 250,
  "exit_code": 0,
  "duration_seconds": 812.3,
  "rate_limit_detected": false,
  "classification": "useful|rate_limited_immediate|rate_limited_midrun|dead_run_short|error|cancelled",
  "commands_executed": 11,
  "useful_output_detected": true
}

1A.3 Classificazione run

Le regole devono essere centralizzate nel helper, non duplicate:

  • rate_limited_immediate: rate limit nei primi 3 turni o nei primi 90 secondi
  • rate_limited_midrun: rate limit dopo lavoro reale
  • dead_run_short: <=3 turni o <90 secondi o nessun comando reale
  • useful: lavoro reale e output utilizzabile
  • error: uscita non prevista
  • cancelled: stop manuale

1A.4 Aggregatore locale

Creare un piccolo report CLI che calcola:

  • spawn/hour
  • useful run ratio
  • dead-run ratio
  • rate-limit ratio
  • avg prompt chars per family
  • estimated static prompt tax per family
  • token per finding confermato

Acceptance Criteria

Prima dello Step 2 devo poter rispondere con numeri a:

  • quale family consuma di piu'
  • quale quota di costo e' bootstrap statico
  • quanti run sono morti o partono gia' in rate limit
  • quanto pesa davvero il proxy analyzer

Rollback

Flag OFF; i call site smettono di scrivere metriche ma continuano a funzionare.

Step 1B: Hardening del Bug Bounty Loop

Obiettivo

Eliminare spawn storm, run morte, retry inutili e loop concorrenti.

File da toccare

Implementazione esatta

1B.1 Control plane unico

Rendere bugbounty/loop-manager.sh il solo control plane.

bugbounty/PERPETUAL-HUNTING-LOOP.sh deve diventare un thin entrypoint che delega al manager e non prende piu' decisioni di scheduling autonome.

1B.2 Singleton lock atomico

Implementare lock con:

  • PID
  • started_at
  • hostname
  • stale timeout

Semantica:

  • se PID attivo: niente nuovo start
  • se lock stale: takeover loggato
  • se lock corrotto: fail closed con messaggio chiaro

1B.3 Global rate-limit sentinel

Riutilizzare in Python la logica regex di scripts/pentest-autoresume.py, salvando stato in bugbounty/.runtime/rate_limit_state.json.

Il manager deve:

  • leggere stato prima di ogni spawn
  • non lanciare nuovi claude -p durante cooldown
  • ridurre concorrenza se la quota e' incerta

Backoff iniziale:

  • evento 1: attesa fino al reset parseato oppure 15 minuti
  • evento 2 ravvicinato: 30 minuti
  • evento 3+: attesa fino al reset reale

1B.4 Dead-run classifier

Un run non utile non deve avanzare la sessione come se fosse utile.

Conseguenze pratiche:

  • non incrementa i contatori di successo
  • non sblocca lo step successivo
  • non scatena nuova ondata immediata di spawn
  • viene contato nella telemetria di burn

1B.5 Runtime separation

Spostare prompt dump e log in:

  • bugbounty/.runtime/prompts/
  • bugbounty/.runtime/logs/
  • bugbounty/.runtime/metrics/

Applicare rotazione minima e retention configurabile.

Acceptance Criteria

  • mai piu' di un orchestratore vivo
  • nessun nuovo spawn durante cooldown
  • i dead run non avanzano il loop
  • riduzione netta di spawn/hour e dead-run ratio rispetto alla baseline

Rollback

Disattivare BB_LOOP_HARDENING; il vecchio flow torna attivo.

Step 2A: Split di skill-boilerplate.md

Obiettivo

Ridurre il costo statico sempre pagato dalle skill di test.

File da toccare

  • .claude/skills/pentest/helpers/skill-boilerplate.md
  • nuovi helper:
  • skill-boilerplate-core.md
  • skill-boilerplate-stealth.md
  • skill-boilerplate-ratelimit.md
  • skill-boilerplate-bugbounty.md
  • skill-boilerplate-proxy.md
  • tutte le skill /test-* che oggi referenziano il boilerplate monolitico

Implementazione esatta

2A.1 Obiettivo dimensionale

skill-boilerplate-core.md non deve superare 15 KB.

Se supera la soglia, il contenuto extra va spostato in un modulo opzionale.

2A.2 Contenuto del core

Restano sempre-on solo:

  • PATH isolation
  • setup EDIR e CONTEXT_FILE
  • structured logging minima
  • kill switch
  • token counting minima
  • auth bootstrap minima

2A.3 Contenuto modulare

  • skill-boilerplate-stealth.md: UA, jitter, proxy rotation, config avanzata stealth
  • skill-boilerplate-ratelimit.md: handler completo dei 429 e policy di retry
  • skill-boilerplate-bugbounty.md: policy-rules, exclusions, out-of-scope patterns
  • skill-boilerplate-proxy.md: wiring proxy-specifico e comportamento con Burp/Caido

2A.4 Refactor skill

Ogni skill /test-* deve:

  • caricare sempre il core
  • caricare i moduli solo se servono al flusso di quella skill o ai flag correnti
  • smettere di dire genericamente "questa skill setta tutto" quando in realta' il setup diventa condizionale

Acceptance Criteria

  • prompt size medio per subprocess in calo di almeno 25% rispetto alla baseline di Step 1A
  • nessuna regressione nei finding sui dataset di verifica
  • nessuna skill /test-* rotta dal nuovo contratto

Rollback

Ripuntare tutte le skill al boilerplate monolitico.

Step 2B: Budget max-turns per Skill

Obiettivo

Evitare turn budget inutilmente larghi sui task piu' deterministici.

File da toccare

Implementazione esatta

2B.1 Classi iniziali

  • deterministic: 80-120
  • medium: 150
  • high: 250
  • very-high: 300 solo se giustificato

2B.2 Mappatura iniziale

  • deterministic: test-infra, test-crypto, test-client, recon, scan
  • medium: test-api, test-ssrf, test-cloud, test-exceptions
  • high: test-injection, test-auth, test-access, test-logic, verify
  • very-high: test-advanced, chain-findings

2B.3 Semantica

Il budget non va hardcoded in tre posti diversi.

Creare una sola source of truth, preferibilmente in JSON o YAML compatto letto da:

  • dispatcher
  • runner
  • eventuali wrapper shell

Acceptance Criteria

  • riduzione del numero medio di turni sulle skill deterministic/medium
  • nessun aumento di exhaust su skill high
  • nessun calo di finding confermati

Rollback

Ritorno al budget uniforme precedente.

Step 3A: POC test-injection con Cross-Type Signal Forwarding

Obiettivo

Dimostrare che una skill pesante puo' essere decomposta senza perdere cross-pollination tra classi di injection.

File da toccare

  • .claude/skills/test-injection/SKILL.md
  • nuovi sottopacchetti, ad esempio:
  • .claude/skills/test-injection-router/SKILL.md
  • .claude/skills/test-injection-sqli/SKILL.md
  • .claude/skills/test-injection-xss/SKILL.md
  • .claude/skills/test-injection-ssti-xxe/SKILL.md
  • .claude/skills/test-injection-cmdi/SKILL.md
  • .claude/skills/test-injection-misc/SKILL.md
  • nuovi helper scope-specifici in test-injection/helpers/

Implementazione esatta

3A.1 Router leggero

La skill principale non contiene piu' tutti i dettagli tecnici.

Fa solo:

  • parse argomenti
  • decide scope
  • invoca la sub-skill corretta
  • legge e consuma i cross-type signals

3A.2 Supporting-files minimali

Ogni sub-skill dichiara solo i supporting files necessari al suo scope reale.

Esempi:

  • test-injection-sqli: knowledge-sqli, cheatsheet-sqli, eventuale knowledge-waf-bypass
  • test-injection-xss: knowledge-xss, knowledge-xss-bypass, cheatsheet-xss
  • test-injection-ssti-xxe: knowledge-ssti, knowledge-xxe, cheatsheet-ssti, cheatsheet-xxe

3A.3 Schema JSONL obbligatorio per cross-type-signals.jsonl

Path:

  • $EDIR/signals/cross-type-signals.jsonl

Schema:

{
  "timestamp": "ISO8601",
  "source_skill": "sqli",
  "target_signal": "ssti",
  "endpoint": "/api/search",
  "request_hash": "sha256",
  "evidence": "template syntax reflected in error message",
  "confidence": "low|medium|high",
  "reason": "why this may indicate the target skill is relevant"
}

Regole:

  • il writer deve essere append-only
  • il router deve deduplicare per request_hash + target_signal
  • i segnali ad alta confidenza devono poter rialzare la priorita' dello scope target

3A.4 Signal forwarding minimo richiesto

Ogni sub-skill deve includere almeno i forwarding piu' ovvi:

  • SQLi -> SSTI, CMDi, XSS, NoSQLi
  • XSS -> SSTI, client-side, markdown/mermaid sinks
  • SSTI/XXE -> CMDi, file disclosure, SSRF
  • CMDi -> path traversal, file write, SSRF

Acceptance Criteria

  • prompt size medio della famiglia injection in calo netto rispetto alla baseline
  • parity di finding tra versione monolitica e split sui dataset scelti
  • nessuna perdita di signal forwarding cross-type nei casi di test creati ad hoc

Rollback

Ritornare alla skill monolitica originale.

Step 3B: Compattazione di agent-dispatch.md

Obiettivo

Ridurre il costo narrativo dell'orchestratore e renderlo machine-readable.

File da toccare

Implementazione esatta

Spostare le mappe ripetitive in JSON compatto e lasciare nel markdown solo:

  • semantica del dispatch
  • invarianti di sicurezza
  • note di utilizzo

Schema target minimo:

{
  "wave_config": {
    "max_waves": 12,
    "agents_per_wave": 3,
    "agents_per_wave_fast": 5
  },
  "model_routing": {
    "test-injection": {"model": "claude-opus-4-6", "thinking_budget": 24000, "max_turns_class": "high"},
    "test-auth": {"model": "claude-opus-4-6", "thinking_budget": 16000, "max_turns_class": "high"},
    "test-infra": {"model": "claude-haiku-4-5-20251001", "thinking_budget": 2000, "max_turns_class": "deterministic"}
  },
  "skill_groups": {
    "deterministic": ["test-infra", "test-crypto", "recon", "scan"],
    "medium": ["test-api", "test-ssrf", "test-cloud"],
    "high": ["test-injection", "test-auth", "test-access", "test-logic"]
  }
}

Acceptance Criteria

  • agent-dispatch.md diventa nettamente piu' corto
  • le decisioni di routing restano equivalenti
  • il dispatcher continua a funzionare leggendo una sola source of truth

Rollback

Ripristinare la versione markdown narrativa precedente.

Step 4A: Novelty Gate del Proxy Analyzer

Obiettivo

Evitare che il proxy analyzer reinvii continuamente traffico ridondante a claude -p.

File da toccare

Implementazione esatta

4A.1 Chiave di novelty

La dedupe non puo' basarsi solo su path grezzo. La fingerprint minima deve includere:

  • method
  • route normalizzata
  • nomi parametri
  • status bucket
  • content type
  • response shape hash
  • presenza di auth header/cookie

4A.2 Gating policy

Auto-analyze continua a esistere, ma l'analisi parte solo se il batch contiene almeno uno dei seguenti:

  • nuova route
  • nuova combinazione method+route
  • nuovo content-type
  • nuovo auth pattern
  • riflessione input
  • 4xx/5xx interessante
  • redirect parameter
  • callback/webhook field
  • upload
  • GraphQL
  • admin/internal path

4A.3 Modalita' di attivazione

Non flip immediato di default.

Prima:

  • novelty gate ON
  • auto analyze invariato
  • shadow metriche per confrontare richieste analizzate vs scartate

Solo dopo parity:

  • valutare auto_analyze=False come default dashboard

Acceptance Criteria

  • riduzione dei batch analizzati senza perdita di finding interessanti
  • nessun tipo di richiesta critica sistematicamente escluso

Rollback

Rimuovere il novelty gate e tornare all'analisi batch precedente.

Step 4B: Differential Rediscovery

Obiettivo

Non rifare discovery completa quando la superficie non e' cambiata, mantenendo un safety net obbligatorio.

File da toccare

Implementazione esatta

4B.1 Manifest minimo

Salvare per ogni engagement:

  • homepage hash
  • robots hash
  • sitemap hash
  • JS asset manifest hash
  • tech stack fingerprint
  • auth surface fingerprint
  • endpoint set hash
  • observed methods hash
  • response header fingerprint
  • websocket presence

4B.2 Trigger di full rediscovery

Scatta full rediscovery se cambia uno dei seguenti:

  • endpoint set hash
  • nuovi metodi HTTP su endpoint esistenti
  • nuovo auth surface
  • nuovi response header rilevanti
  • nuovo websocket endpoint
  • delta sopra soglia configurata

4B.3 Safety net obbligatorio

Anche senza delta rilevato, forzare full rediscovery ogni 5 cicli.

Variabile:

  • BB_FORCE_FULL_REDISCOVERY_EVERY_N=5

Acceptance Criteria

  • calo del costo rediscovery nei loop ripetuti
  • nessuna perdita di coverage nei casi con superficie stabile
  • almeno un full refresh ogni 5 cicli verificabile nei log

Rollback

Disattivare DIFFERENTIAL_REDISCOVERY e tornare sempre alla full rediscovery.

Step 5A: Decomposizione delle Altre Skill Pesanti

Ordine finale

  1. test-auth
  2. test-llm
  3. test-access
  4. test-client
  5. test-logic

File da toccare

Implementazione esatta

Applicare lo stesso pattern della POC:

  • router leggero
  • supporting-files minimali
  • forwarding dei segnali rilevanti verso skill adiacenti
  • parity test
  • feature flag per skill

Esempi minimi di forwarding:

  • test-auth -> test-access, test-logic
  • test-llm -> test-client, test-api
  • test-access -> test-auth, test-logic
  • test-client -> test-auth, test-access
  • test-logic -> test-access, test-auth, test-api

Acceptance Criteria

  • ogni skill decomposta dimostra parity con la baseline sul proprio dataset
  • il costo statico medio cala dopo ogni decomposizione
  • nessuna decomposizione entra in produzione senza feature flag

Rollback

Per-skill, senza impattare le altre decomposizioni gia' validate.

Step 5B: pentest/SKILL.md Phase-Specific Loading

Obiettivo

Ridurre il costo dell'orchestratore principale, che oggi carica istruzioni di fasi non attive.

File da toccare

  • .claude/skills/pentest/SKILL.md
  • nuovi helper per fase, ad esempio:
  • .claude/skills/pentest/helpers/pentest-phase-preflight.md
  • .claude/skills/pentest/helpers/pentest-phase-recon.md
  • .claude/skills/pentest/helpers/pentest-phase-discovery.md
  • .claude/skills/pentest/helpers/pentest-phase-scanning.md
  • .claude/skills/pentest/helpers/pentest-phase-testing.md
  • .claude/skills/pentest/helpers/pentest-phase-verification.md
  • .claude/skills/pentest/helpers/pentest-phase-reporting.md

Implementazione esatta

Tenere in pentest/SKILL.md solo:

  • usage e flag
  • semantica globale
  • state machine delle fasi
  • regole di sicurezza invarianti

Spostare i blocchi operativi voluminosi nei helper phase-specific e caricarli solo nella fase attiva.

Acceptance Criteria

  • pentest/SKILL.md diventa sostanzialmente piu' corto
  • nessuna fase perde istruzioni operative
  • l'orchestratore continua a dispatchare con comportamento equivalente

Rollback

Ripristino del file monolitico.

Step 5C: Safety Preamble Centralizzato

Obiettivo

Eliminare duplicazione safety comune nelle skill di test.

File da toccare

  • nuove helper condivise in .claude/skills/pentest/helpers/
  • skill /test-* che duplicano il framing safety

Implementazione esatta

Estrarre una safety preamble unica e riutilizzabile per:

  • non-destructive testing
  • verification minima richiesta
  • evidenza obbligatoria
  • out-of-scope and BB policy reminders

Lasciare dentro ogni skill solo il delta domain-specific.

Acceptance Criteria

  • riduzione della duplicazione ripetitiva
  • nessuna perdita di guardrail safety

Rollback

Reinserire la safety nel testo delle skill.

Step 6: Lane B opzionale in Shadow

Obiettivo

Valutare routing di task deterministici a lane piu' economiche senza rischio operativo.

File da toccare

Implementazione esatta

Solo shadow mode. Nessuna decisione di sicurezza vera dipende dalla lane B.

Task candidati:

  • normalizzazione route
  • clustering endpoint equivalenti
  • hash response body
  • parsing sitemap/robots
  • diff di JS manifest

Task esclusi:

  • exploit reasoning
  • stuck resolution
  • finding acceptance
  • verification
  • chain discovery

Acceptance Criteria

  • parity stabile in shadow
  • zero falsi negativi sui task target

Rollback

Spegnere LANE_B_SHADOW.

Piano di Validazione

Regola generale

La validazione e' per fase, non solo cumulativa.

Ogni fase ha go/no-go indipendente.

Dataset minimo

  • almeno 3 engagement reali o lab comparabili per pentest flow
  • almeno 5 cicli ripetuti per valutare loop e rediscovery
  • almeno 1 dataset dedicato per parity delle skill decomposte

Soglie decisionali

  • miglioramento token significativo: almeno 20% sulla metrica target della fase
  • regressione finding accettabile: zero su finding confermati
  • regressione coverage accettabile: zero sulle classi in scope della fase
  • aumento false positive: tollerato solo se non impatta la verification downstream

Go/No-Go

  • go automatico solo se tutte le soglie sono rispettate
  • altrimenti review manuale prima di procedere

Caso ambiguo

Se una fase migliora i token ma peggiora una metrica secondaria:

  • si resta in flag ON solo in shadow
  • niente graduation a default

Cosa Non Implementerei Subito

  • riduzione aggressiva di CLAUDE.md
  • flip immediato di auto_analyze=False come default dashboard
  • routing di task non deterministic su lane economiche
  • decomposizione simultanea di piu' skill senza avere prima validato la POC
  • modifiche metodologiche al pentest vero e proprio

Decisione Operativa

Se si parte, l'ordine corretto e':

  1. Step 0
  2. Step 1A + 1B
  3. Step 2A + 2B
  4. Step 3A + 3B
  5. Step 4A + 4B
  6. Step 5A + 5B + 5C
  7. Step 6 solo se tutto il resto e' stabile

Questo e' il piano definitivo che implementerei io nel repo.