Skip to content

Perpetual Hunting Loop

The perpetual bug bounty loop is the always-on background hunting system. It is separate from the interactive /bb-session skill even though they share the same program intelligence, policy, submission, and learning services.

Control Plane

The perpetual system has two layers:

  • bugbounty/loop-manager.sh
  • bugbounty/PERPETUAL-HUNTING-LOOP.sh

The manager is the control plane. The worker runs one hunting session at a time.

Manager responsibilities

The manager owns:

  • lock handling
  • single-instance protection
  • session scheduling
  • console and runtime logs
  • rate-limit and cooldown state
  • useful-run vs dead-run classification
  • cooldown maintenance tasks when Claude is waiting

Worker responsibilities

The worker owns:

  • dashboard authentication
  • platform sync and change refresh
  • AI account binding
  • program selection
  • wave-based hunt execution
  • live event emission
  • finding gating
  • compact memory production

Dashboard Control Surface

The dashboard exposes the perpetual loop through:

  • POST /api/v1/bugbounty/loop-control
  • GET /api/v1/bugbounty/loop-config
  • POST /api/v1/bugbounty/loop-config
  • GET /api/v1/bugbounty/hunting-log
  • POST /api/v1/bugbounty/hunting/event
  • GET /api/v1/bugbounty/hunting/status
  • GET /api/v1/bugbounty/hunting/events
  • GET /api/v1/bugbounty/hunting/findings

This gives the UI start, stop, restart, status, configuration, and live telemetry without embedding loop logic in the frontend.

Codex-Heavy Architecture

The perpetual loop is intentionally more Codex-heavy than the interactive bug bounty flow.

Claude owns

  • live testing against the target
  • dynamic interpretation of ambiguous behavior
  • final exploit validation
  • final call on borderline real-world behavior

Codex owns or supports

  • selection reranking support
  • compact runtime advisory
  • discovery digestion
  • weak-signal triage
  • chain planning
  • finding-side FP gate support
  • session memory compaction
  • cooldown maintenance work

The architectural goal is to keep Claude concentrated on live offensive reasoning and move bounded, token-heavy support lanes to Codex.

Session Cycle

A typical perpetual session looks like this:

  1. authenticate against the dashboard
  2. sync platforms and refresh recent program changes
  3. bind active bug bounty Claude and Codex accounts
  4. select programs from the intelligence pool
  5. ensure program workspaces exist in canonical form
  6. run hunts in waves
  7. emit live events to the dashboard
  8. gate and store candidate findings
  9. write compact memory artifacts
  10. classify the session and schedule the next one

AI Account Binding

The worker reads bug bounty enabled accounts from the AI account API and binds separate Claude and Codex identities for the loop runtime. This avoids relying only on one global default account and lets the bug bounty subsystem use the accounts that are explicitly enabled for that use case.

Workspace Compatibility and Artifacts

The loop works against program-scoped workspaces and automatically bridges the old and new layouts.

Canonical per-program layout

bugbounty/programs/{platform}/{handle}/
  findings/
  pending-findings/
  rejected-findings/
  evidence/
  logs/
  .fp-gate/
  memory/

The runtime can import missing artifacts from legacy paths under bugbounty/{platform}/{handle}/, which allows the new loop to reuse older program history without a hard migration cutover.

Runtime directory

The perpetual manager also keeps process state under:

bugbounty/.runtime/

That area stores:

  • prompts
  • hunt logs
  • pending metrics
  • Codex advisory metrics
  • Codex loop metrics
  • control state

Wave-Based Hunting

The worker runs hunts in waves rather than one monolithic session. This makes it easier to:

  • inject compact Codex advisory at checkpoints
  • rotate targets without losing the full session
  • classify stalled or dead runs
  • persist intermediate memory safely

Wave count and duration are configurable through environment variables such as:

  • BB_HUNT_WAVE_COUNT
  • BB_HUNT_WAVE_SECONDS

Live Events

The worker posts structured events to the dashboard during execution. These include events like:

  • session start and end
  • hunt start and progress
  • policy fetch
  • knowledge load and save
  • finding events

The dashboard stores recent events in memory, exposes them via admin APIs, and can broadcast them over WebSocket to live views.

Cooldown Handling

Claude rate limits are treated as a normal operational state, not a failure mode.

When a cooldown is active, the manager can trigger Codex-side maintenance tasks instead of idling completely. Typical maintenance work includes:

  • memory compaction
  • backlog preparation
  • workspace normalization
  • selection refresh
  • precomputation for future waves

This is a large part of what makes the perpetual loop economically different from the manual flow.

Finding Gating

The perpetual runtime no longer needs to treat every detection as an immediate final finding.

It supports staged handling through directories such as:

  • pending-findings/
  • rejected-findings/
  • findings/

This lets the runtime hold weak signals until they pass stricter checks instead of promoting them too early.

Metrics and Tuning

The loop writes lightweight metrics files so effectiveness can be tuned from real sessions:

  • bugbounty/.runtime/metrics/codex-advisory.jsonl
  • bugbounty/.runtime/metrics/codex-fp-gate.jsonl
  • bugbounty/.runtime/metrics/codex-loop.jsonl

These logs capture how advisory and gate lanes are being used, which is critical when the loop is designed to shift as much bounded work as possible onto Codex without reducing finding quality.