adshao/flounder: an autonomous white-hat auditor that wraps a coding agent in sandbox and execution gates

What Flounder actually solves, and for whom

Coding agents can read a repository and produce a plausible vulnerability write-up. What they cannot do on their own is prove the write-up. Flounder exists to close that gap: it is described in the README as "a thin white-hat audit workflow around the model," where the model decides how to reason about the target and the surrounding system supplies the sandbox, command policy, durable state, execution gates, daemon control plane and reporting. The intended user is a security engineer or bug-bounty researcher who already has an agent and wants the audit loop, not another prompt.

The README is explicit about what it is not: not a scanner for one stack, not a checklist runner, not a set of hand-written bug rules. That distinction matters for adoption. If your workflow depends on a fixed rule set you can diff between releases, Flounder is the wrong shape. If your workflow depends on an agent exploring an unfamiliar codebase and being forced to back its claims with a command that ran, it is aimed at you.

The README lists the scenarios it is meant to cover: blind capability audits, incident investigation from suspicious on-chain evidence, open-world bug-bounty audits, targeted follow-up on suspected findings, and disclosure preparation. Whether Flounder prepares the target itself or you hand it source paths is treated as an input path, not a separate scenario.

The run pipeline: prepare, map, dig, synthesize, verify, confirm, report

The mechanism is a tracked workflow. According to the README, `flounder run <clue>` executes prepare, map, dig, synthesize, verify, confirm and report as one tracked pipeline. Prepare can turn a transaction, address, project, repository or link into staged source and materials. Map inventories the audit surface. Dig writes and runs proof tests. Synthesize composes cross-scope candidates. Verify confirms or refutes candidates by local execution. Confirm reproduces findings on the real target, and report packages reproduced bugs into Markdown reports.

Two design details stand out. First, coverage is versioned: scope inventories and model memory are bound to the prepared-material fingerprint, independent Map inventories are unioned without dropping singleton scopes, and every Dig writes a separate obligation and composition outcome. Incomplete outcomes stay visible, and cross-scope synthesis runs even when individual scopes produced no finding. That is a deliberate answer to the failure mode where a missed scope silently disappears from the report.

Second, the finding gate is execution, not opinion. The README states that a finding must cite a passing local command that exercises the vulnerable path, and that stronger findings also pass differential confirmation, independent refutation and faithful-PoC appeal checks. Discovery runs network-sealed so findings come from the target material rather than from public disclosures; during `flounder confirm`, only explicit read, fork and fetch commands receive egress. Arbitrary model code stays sealed. That split is the most interesting part of the design, and it is also where the operational burden lands on you: if your target needs a network call the policy does not classify as read, fork or fetch, confirm will not reach it.

Installing the Flounder skill and running a first audit

Flounder is distributed as an agent skill, so the install step is one command even when you do not have the source checkout locally. The README gives this exact form, targeting Codex and Claude Code:

npx skills add adshao/flounder --skill flounder -g -a codex -a claude-code

If you are already inside a local checkout and want the checked-out copy rather than the published one, the README gives the alternate form:

npx skills add . --skill flounder -g -a codex -a claude-code

After that, you drive it through the agent in natural language rather than through a CLI invocation. The README's example prompt is:

Audit this repository with Flounder.

The README says the installed skill should trigger on requests about Flounder audits, public-source or authorized source review, smart-contract and ZK audit work, daemon and provider setup, verifying suspected findings, confirming real findings, and collecting execution-backed bug reports. The source of truth for the skill's behaviour is `skills/flounder/SKILL.md`, and the README points to `docs/USAGE.md` for usage and `docs/ARCHITECTURE.md` for architecture. The README does not document a rollback or uninstall path for the installed skill.

If you want the CLI directly, `package.json` declares a `flounder` bin pointing at `./dist/cli.js`, with `npm run build` producing the server and UI bundles. Note the engine constraint in `package.json`: `node >=24.13 <25`. That is a narrow window and it will bite anyone on an LTS line.

The sandbox boundary is the real product, and the real constraint

Model-generated code, PoCs, dependency installs and local tests run in a copied workspace rather than the host checkout. The README describes the default OCI backend as refusing silent host execution, bind-mounting only the copied workspace and package cache, dropping Linux capabilities, using `no-new-privileges`, read-only root filesystems and tmpfs temp dirs, applying process, memory and CPU limits when configured, and disabling network for sealed audit commands.

That is a strong default, and it is also the constraint. An OCI backend means a container runtime has to be present and working on the machine doing the audit. The README does not document a fallback for environments without one, and it does not describe what happens when the backend is unavailable; it describes the backend refusing silent host execution, which implies the safe failure is refusal rather than degradation. If you were hoping to point Flounder at a repository on a laptop with no container runtime and get results, the documentation does not promise that.

There is a second cost that is easy to miss. The audit is grounded in local execution, which means the target has to be runnable locally. The README names Solidity/EVM and ZK as strong fits precisely because local forks with Foundry or Hardhat tests can prove on-chain effects, and local prover and constraint harnesses can turn a missing constraint into an executable counterexample. It calls those high-signal examples rather than hard-coded limits. Read that as: framework-agnostic in principle, but the quality of the proof depends on whether you can stand the target up.

Durable groups, maintainer experiments, and where the surface stops

Two subsystems sit outside the ordinary audit path. `flounder group` runs validated positive, negative, control, replay and multi-target work items through the same daemon queue and audit kernel, with group concurrency, attempts, blocked setup, evidence outcomes and reports surviving control-plane restarts. The README states that manifest-provided commands are never executed directly, host execution is rejected, and lifecycle state stays separate from security and scoring outcomes. That last separation is the one to check if you plan to build dashboards on top of the API: a run being finished is not the same field as a run having found something.

The second is `flounder experiment`, which only appears when the control plane is started with `flounder ui --maintainer`. It helps a Flounder maintainer agent mine verifier-grounded evaluation failures, constrain source proposals to an allowlist, and compare paired baseline and candidate runs. The README says it is not triggered by ordinary projects and is absent from the default user surface, and that promotion requires distinct cases and bug families, passing hidden holdouts and controls, and no paired regressions, with merge and deployment remaining human gates. Treat this as a maintainer tool, not a feature you configure on day one.

The integration surface is broad: a CLI, a React dashboard, a self-describing REST API, a pi extension, provider profiles and a daemon execution plane, with example provider files at `examples/models.claude-code.json` and `examples/models.codex.json`. The README says Codex-style and Claude Code-style providers can be routed through the same sandbox and audit contract. The README's section on local control of code and credentials is truncated in the repository listing, so the credential-handling story is one you have to read in the full file before committing to a deployment.

How it differs from Semgrep and rule-based scanners

The obvious alternative is a rule-based static analyzer such as Semgrep. The difference is not quality, it is where the intelligence lives. A Semgrep ruleset encodes a pattern a human already thought of; you can read the rule, version it, and predict which lines it will match. Flounder encodes no stack-specific strategy at all. The README says Flounder does not encode a Solidity/EVM, ZK, Rust, Go, JavaScript, protocol or crypto-specific audit strategy, and that source, corpus and optional profiles are inputs while the audit strategy comes from the model.

That trade is concrete. With Semgrep you get reproducibility and a diffable rule set, and you get nothing for a bug class nobody has written a rule for. With Flounder you get coverage of the unfamiliar, and you get a result whose quality moves with the model behind it. The README frames this as a benefit: as coding models improve, audit capability can improve without rewriting the framework. It is also the reason a Flounder finding is harder to audit than a rule match, which is presumably why the execution gate exists in the first place.

A second alternative is simply running your existing agent against the repository with no framework. You would get reasoning, and you would lose the sandbox, the durable state across restarts, the sealed discovery phase, the egress allowlist during confirm, and the requirement that a finding cite a passing command. Whether those are worth an OCI dependency and a Node version pin is the actual adoption question.

Licence, maintenance and what an upgrade costs

The repository is not archived, and the last push was on 2026-09-16, one day before this writing, so the codebase is moving. There are no releases retrieved, so there is no tagged version history to pin against; `package.json` shows version 0.4.0, which is pre-1.0 and should be read as such.

The licence is AGPL-3.0, declared as `AGPL-3.0-only` in `package.json`. That is a strong copyleft licence with a network-use clause, and it is the single fact most likely to decide adoption for a company rather than an individual. Running Flounder locally to audit your own code and writing up the findings is one thing; offering an audit service built on modified Flounder source is another. This is not legal advice, and the distinction between those two situations is exactly the kind of question your counsel should answer before you build a product on it.

Upgrade cost has two visible sources. The first is the Node engine range, `>=24.13 <25`, which means a Node major bump can lock you out until the project widens the range. The second is that the audit contract is tied to prepared-material fingerprints and versioned scope inventories, so a change in how material is prepared can invalidate cached coverage. The repository ships `scripts/check-db-upgrade.mjs` and `scripts/check-api-catalog.mjs`, plus `npm run check:public` for the public surface, which suggests the maintainers treat schema and API drift as a first-class concern. The README does not document a migration procedure for existing audit state across versions.

Editorial conclusion

Adopt Flounder if you already drive Codex, Claude Code or a similar skills-aware agent and you want the audit loop, sandbox and execution gate handled for you; it fits Solidity/EVM and ZK work best because local forks and prover harnesses can prove real effects. Do not adopt it if you need a deterministic rule-based scanner, a hosted service, or anything on Node other than >=24.13 <25. Before trusting a run, verify your OCI backend actually refuses host execution, that your provider profile is wired through configs/ and examples/, and that the AGPL-3.0-only licence is acceptable for how you plan to ship the output.

Frequently asked questions

Official sources

1. adshao/flounder on GitHub
2. Issues
3. License: AGPL-3.0
4. Project website
5. README