Flounder

Flounder

This skill is the operating manual for Flounder-driven security audits.

Flounder is an autonomous white-hat security auditor. The agent prepares the target, audits source, constructs exploit paths, runs local proof tests, confirms real findings, and packages reports. The framework provides the daemon, sandbox, command policy, run tracking, live activity, and execution gates.

Skill Files

Use progressive disclosure: open only the reference file needed for the current task. Do not duplicate long command references into the conversation when a short command and status summary is enough.

What This Skill Must Do

• Turn a security-audit request into a public-source or authorized Flounder project or run.
• Keep the operator on the current workflow: run <clue> lets Flounder prepare the target, then map/dig/synthesize/verify, confirm, and report; run --source is the source-provided entry path for sealed map/dig/synthesize/verify.
• Prefer the dashboard/API control plane for project work so state, daemon ownership, live logs, findings, and reports stay durable.
• Preserve the evidence ladder: suspected, locally confirmed, real-target reproduced, submission-ready. Do not collapse these into one "bug" bucket.
• Use run health and discovery backlog rows when judging progress: a shallow or resource-blocked zero-finding run is not a negative result, and follow-up scopes should stay as pending coverage rather than becoming findings.
• Separate machine noise from active work by marking dismissed findings ignored, never by deleting them.
• Stop with a clear next action or blocker; do not call an audit complete just because a command exited.

Core Audit Modes

Choose the mode from the user's intent before launching anything:

When in doubt: if the user asks to measure Flounder's unaided recall, use blind capability audit and keep the clue target-only. If the user gives live exploit evidence, use incident investigation. If the user wants broad public-source or authorized bug hunting and permits public context collection, use open-world public-source audit.

Supporting Workflows

Use these when the user is not asking for a full end-to-end audit:

Core Operating Rules

• Use Flounder CLI, dashboard, REST API, or pi extension workflows. Do not edit the tracking database directly.
• Confirm authorization and scope before running an audit.
• Keep provider credentials daemon-local. The server stores provider profiles; daemons own provider login, API keys, target source, and execution.
• Treat ~/.flounder as the default product home: tracking DB, run artifacts, durable history/build cache, daemon workspace, and daemon-local provider auth live there unless the user explicitly passes --out or --workspace.
• Start with flounder ui unless the user already has a control plane running. CLI verbs are thin clients of that control plane.
• Start with flounder ui --maintainer only when an authorized Flounder maintainer is improving Flounder source. Ordinary Project and Evaluation work must not enable or advertise Harness source-improvement operations.
• Use GET /api before driving the REST API directly; the catalog is the source of truth for endpoint shape.
• Use project-owned docs/specs/audits as corpus. Do not write answer-bearing corpus that names the suspected bug, location, or mechanism.
• Do not modify target source in place. Flounder copies a build root into an isolated workspace and model-written tests stay inside that workspace.
• Treat suspected as unproven. A finding is actionable only when execution produced confirmed-executable, confirmed-differential, or a reproduced confirm decision.
• flounder run <clue> is the one-command workflow: open-world prepare, sealed map/dig/synthesize/verify, open-world confirm, then report generation. flounder run --source, map, and audit are sealed discovery phases. prepare and confirm are open-world phases, still under white-hat no-broadcast rules.
• Never broadcast transactions, move funds, submit writes, persist access, or target systems outside the declared local audit boundary or explicit authorized scope.

First Response Checklist

When a user asks to audit, confirm, verify, report, or inspect Flounder state:

1. Confirm the target source is public, operator-owned, client-authorized, or in public bounty scope. If the source boundary is unclear, ask before running.
2. Classify the request into one core audit mode: blind capability audit, incident investigation, open-world public-source audit, normal bug bounty, or bug bounty contest.
3. Decide the surface:
   • Existing dashboard/API project: use GET /api, then project UUID routes.
   • New project or local operator workflow: start/reuse flounder ui.
   • Framework-prepared target: prefer task/clue so Flounder can prepare source and official materials.
   • Source-provided target: use --source when code is staged or no external preparation is wanted.
4. Check daemon and provider readiness before launching real model work: flounder daemon provider check openai-codex on the executor machine.
5. Check sandbox readiness before execution-confirming audits: npm run sandbox:build if the default OCI image is missing.
6. Choose the workflow from the routing table below, launch the smallest correct action, then monitor live logs and persisted state.
7. Report the result with project/run ids, phase, evidence status, and next action. Include setup blockers distinctly from audit findings.

For repository development or local builds, use Node 24 LTS from .nvmrc / .node-version; do not substitute newer experimental Node versions.

Quickstart For Codex Or Claude Code

1. Check whether Flounder is available:

   flounder --help

   If it is not available from PATH but the repository is checked out, build it:

   npm install
   npm run build
   node dist/cli.js --help

   Until the package is installed or linked, replace flounder in command examples with node dist/cli.js.

2. Start or reuse the local control plane:

   flounder ui

   For a remote executor, mint a token in Settings or with flounder server daemon-token mint, then run:

   flounder daemon start --server http://<server>:4500 --token <token>

3. Authenticate every provider that the selected daemon will run. For model selection or credential setup, read the model setup guide. Use OAuth login only for OAuth-capable providers; API-key providers need keys in the daemon environment or an existing stored pi credential. Coding Plan subscriptions may also use API keys. Preserve the user's selected provider and plan; do not assume they need a new adapter or metered endpoint.

   OAuth example:

   flounder daemon provider login openai-codex
   flounder daemon provider check openai-codex

   For openai-codex, this is how the agent asks the user to authenticate. Run the login command in the terminal; it prints a browser URL or device-code instructions, the user completes the login, and then check verifies it. If pi already has openai-codex in ~/.pi/agent/auth.json, Flounder imports that provider entry into ~/.flounder/agent/auth.json on login/check.

4. Ensure the execution sandbox is available on the daemon machine. Default auto mode prefers Apple's container runtime on Apple silicon macOS when the selected image and sealed network are ready, then falls back to Docker-backed OCI when the image is available. For the Docker-backed path, install and start Docker or a Docker-compatible runtime, then build the default sandbox image from the Flounder repo:

   npm run sandbox:build

   Curated target-specific images are available for common non-EVM audits:

   npm run sandbox:rust:target -- --target <target-root> --execute
   npm run sandbox:cairo:build  # flounder-sandbox:cairo, Scarb + Starknet Foundry
   npm run sandbox:ton:build    # flounder-sandbox:ton, TON Blueprint + FunC/Tolk/Tact

   On Apple silicon macOS daemon hosts, install/start Apple's container runtime and build or pull the selected image into that runtime to let auto select it; --sandbox-backend apple-container requires that path explicitly. If no sandbox engine is available, only use --sandbox-backend host --allow-host-execution for trusted local smoke tests after warning the user that host mode lacks kernel-level filesystem and network isolation.

5. Create or reuse a provider profile in Settings. A provider profile selects provider, model, and thinking level. Fresh stores seed openai-codex · gpt-5.6-sol · xhigh, openai-codex · gpt-6-astra · medium, and claude-code · opus 4.8 max; the selected daemon still needs local auth for every provider the project can use. A project can override the profile per phase: prepare, map, dig, confirm. Set default makes a profile the local default for new projects, evaluations, and API/CLI launches that omit an explicit model; Use product default restores the packaged gpt-5.6-sol fallback without changing existing projects.

   The optional openai-codex · gpt-6-astra · medium starter profile does not replace the Sol product default. Selecting Astra in the provider editor initializes medium thinking; the operator may override it. Custom model ids use a known same-provider Compatibility base for transport, context, tool, and reasoning metadata. The job carries the definition to the selected daemon in memory; credentials remain daemon-local, and no matching daemon-local pi models file is needed. The provider must actually authorize the custom model id.

6. Create or reuse a project. Set:

   • task/clue in the project composer
   • execution daemon
   • default provider profile
   • project directory under the daemon workspace, defaulting to the project UUID
   • source paths
   • build root
   • corpus paths
   • coverage and budget controls

7. Start the audit. Leave Run after create checked to launch immediately, or use the project Run button before the first pipeline run and Continue afterward. For a clue:

   flounder run <tx-or-address-or-project-or-repo-or-link>

   For source already on disk:

   flounder run --target <name> --source <paths...> --build-root <root> --corpus <docs...>

8. Monitor progress from the dashboard, CLI stream, or REST API:

   • current phase: prepare, map, dig, synthesis, verify, confirm, report
   • live activity: GET /api/runs/:id/log
   • project state: GET /api/projects/:uuid
   • prepare quality: prepareSummary.quality is ready, limited, preparing, needs-review, missing, or invalid; use prepareSummary.auditReady as the automation gate. limited means the audit can continue automatically while recorded trust boundaries or material gaps stay visible for later confirm/report decisions. Stop only for prepareSummary.blockingIssues, invalid, or missing usable source.
   • findings: GET /api/projects/:uuid/findings?tracking=active
   • ignored findings recovery: GET /api/projects/:uuid/findings?tracking=ignored
   • confirm decisions: GET /api/projects/:uuid/confirm-decisions
   • run health: latestRunHealth.status is healthy, needs-coverage, needs-resource, shallow, or infra-failed
   • discovery backlog: GET /api/projects/:uuid/backlog?status=open lists coverage gaps, resource requests, and follow-up scopes with actionability, action_owner, and recommended_action; treat open rows as an agent-owned queue (agent-runnable, agent-resource, agent-review) and use PATCH /api/backlog/:id to mark rows resolved, ignored, stale, or back to open

   Project names are display labels. Resolve a project UUID from POST /api/projects or GET /api/projects; do not build a project URL from the name.

9. Decide the next action using the rules below. Do not call the task complete just because one run ended.

Fast Recipes

Blind Capability Audit

Use this when the user wants no hints, no incident context, or a framework-capability check.

Recommended target-prepared path:

flounder run <project-or-repo-or-package-link>

Existing source path:

flounder run --target <name> --source <paths...> --build-root <root> --corpus <user-supplied-docs...>

• Leave --corpus empty unless the user supplied official docs/specs as part of the blind package.
• Do not use incident reports, known bug names, exploit theories, hand-written scope notes that point at a suspected bug, or answer-bearing corpus.
• Judge the result by evidence status and coverage: mapped scopes, audited scopes, suspected findings, locally confirmed findings, pending scopes.
• A negative result is "no confirmed finding in covered scope", not proof the target is safe.

Incident Investigation From A Transaction Or Address

Use this when the user gives a suspicious transaction, address, exploit link, or asks "why was this hacked?"

flounder run <tx-or-address-or-incident-link>

• Let Prepare collect deployed source, chain facts, official project material, and real-target confirmation requirements.
• Keep the incident clue factual. Do not write a theory of the bug into corpus.
• Confirm the root cause with attacker-real local reproduction, usually a local fork or source-level replay. Never broadcast or write to a live system.
• The answer should explain the exploited invariant, attacker path, affected component, and whether the finding is reproduced, not-reproduced, or still suspected.

Open-World Public-Source Audit

Use this when the user wants Flounder to actively collect official public context, deployments, package metadata, docs, or bounty scope when available. Source paths are useful when already available, but they are not what defines the scenario. A public bounty is a priority and submission-path signal, not a prerequisite for local sealed audit.

1. Start or reuse flounder ui.
2. Create a project with:
   • local source/build/corpus paths if available;
   • a task/clue naming the project, repo, bounty page, deployment, or package;
   • an online daemon;
   • a provider profile such as openai-codex · gpt-5.6-sol · xhigh.
3. Leave Run after create checked when the user wants immediate execution.
4. Monitor GET /api/runs/:id/log and GET /api/projects/:uuid.
5. Treat limited prepare as audit-ready unless it has blocking issues; carry caveats forward to verify/confirm/report decisions.
6. Use official/public materials only; do not add private notes or answer-bearing docs that name a suspected bug.

Normal Bug Bounty

Use this when the target is a normal public or private bounty program and a live target may need real-world reproduction.

1. Create a project with config.engagement.kind="bug-bounty".
2. Provide local source/build/corpus paths when available, plus a task/clue naming the official program, scope, deployment, or package.
3. Let Prepare collect public scope, deployments, provenance, and known-issue leads.
4. Run sealed map/dig/synthesize/verify for local proof.
5. Run Confirm for locally confirmed findings when live-target reproduction is required or useful.
6. Submit only findings that pass scope, duplicate, known-issue, impact, payout-readiness, and white-hat disclosure gates.

Bug Bounty Contest

Use this when the venue is a time-limited audit contest with source, rules, and a report format.

1. Create a project with config.engagement.kind="bug-bounty-contest".
2. Configure contest strategy to favor fast settled loops, for example batchScopes:10, digConcurrency:5, skipRealTargetConfirm:true, and appendMapWhenExhausted:true when the rules are source-only.
3. Before opening more scopes, settle existing candidates through verify/refute and report. Contest mode is speed-oriented, but suspected-only findings still do not meet the submission bar.
4. Use duplicate tracking against already submitted issues and local findings before submitting a new report.
5. When mapped scopes are exhausted, append-map to add novel scopes while preserving audited status, submitted findings, duplicate links, and reports. Do not remap unless the operator intentionally wants a fresh inventory.
6. Watch contest stop-review signals: elapsed review window, exhausted inventory, recent low-yield batches, duplicate rate, report backlog, and open resource requests.