flounder wraps modern coding agents in a sandboxed, white-hat audit pipeline that maps attack surface, proves findings by local execution, and reproduces confirmed bugs for authorized targets.
| Tool | adshao/flounder — an autonomous white-hat security auditor that turns coding agents into an end-to-end, execution-grounded audit system |
| Category | Security automation / autonomous agent framework (TypeScript, AGPL-3.0) |
| Primary Use | Authorized audits of repositories, packages, and deployed clues, with a strong fit for Solidity/EVM and ZK proof-system targets |
| Safe Use | Intended for authorized engagements: public-source targets, sanctioned bug-bounty scopes, and private code the operator is permitted to audit |
| Telemetry Note | Discovery is network-sealed and all model code runs in an OCI sandbox; flounder confirm permits only explicit read/fork/fetch egress, giving defenders a narrow, observable traffic profile |
flounder is a TypeScript project, licensed AGPL-3.0 and sitting at around 512 stars on GitHub, that positions itself as an autonomous white-hat security auditor rather than another static scanner. The core idea is to take a modern coding agent — Codex, Claude Code, or any skills-aware model — and wrap it in a thin, disciplined audit workflow. You hand it a clue: a repository, source tree, package, deployed address, transaction, or prior run, and the agent prepares the workspace, reads the code, maps the attack surface, digs into promising regions, constructs candidate exploit paths, runs local proofs, and reproduces confirmed findings against real ground truth. The repository's topic list (audit, security-automation, smart-contracts, solidity, zero-knowledge, bug-bounty) tells you where the author expects the highest signal.
The philosophical distinction the README insists on is that flounder is not a per-stack scanner, a checklist runner, or a bundle of hand-written bug rules. It deliberately encodes no Solidity/EVM, ZK, Rust, Go, or JavaScript-specific audit strategy. Instead, the framework supplies the operational scaffolding — sandbox, command policy, durable state, execution gates, a daemon control plane, and reporting — while the model itself decides how to reason about the target. That inversion matters: as coding models improve, the audit capability improves without anyone rewriting the framework around each new stack. The tradeoff is that output quality is bounded by the model's reasoning, and flounder compensates with hard evidence gates rather than trusting plausibility.
The audit loop is expressed as a tracked workflow: flounder run <clue> executes a prepare -> map -> dig -> synthesize -> verify -> confirm -> report pipeline. Prepare turns a transaction, address, project, repository, or link into staged source and supporting materials. Map inventories the audit surface. Dig writes and runs proof tests. Synthesize composes cross-scope candidates from separate digging outcomes, and it runs even when individual scopes produced nothing — a nice detail, since cross-scope interaction bugs are exactly where per-file auditors go blind. Verify confirms or refutes candidates by local execution, confirm reproduces surviving findings on the real target, and report packages reproduced bugs into Markdown reports.
The most operationally interesting design decision is execution-grounded findings. The README is blunt: a finding is not real because the model says it is plausible — it must cite a passing local command that exercises the vulnerable path. Stronger findings additionally pass differential confirmation, independent refutation, and faithful-PoC appeal checks. This is a meaningful answer to the hallucination problem that plagues LLM-assisted auditing, and it cleanly separates flounder from tools that emit a wall of speculative issue text. For a professional triaging agent output, the difference between a suspected, verified, confirmed, and reproduced finding is preserved in state rather than flattened into one bucket.
The sandboxing story is unusually detailed for this category of tool. Model-generated code, PoCs, dependency installs, and local tests all run in a copied workspace, never directly in the host checkout. The default OCI backend refuses silent host execution, bind-mounts only the copied workspace and package cache, drops Linux capabilities, applies no-new-privileges, uses read-only root filesystems and tmpfs temp directories, enforces process/memory/CPU limits when configured, and disables network for sealed audit commands. The stated goal is limiting the blast radius of malicious dependencies, unsafe PoCs, and model mistakes — a realistic threat model when you are letting an agent install packages and execute generated code.
Egress policy is split by phase. Discovery runs fully network-sealed, so findings are derived from the target material rather than copied from public disclosures — which also makes the tool honest for blind-capability testing. During flounder confirm, only explicit read, fork, and fetch commands receive egress for white-hat reproduction and novelty checks, while arbitrary model code stays sealed. From a defender's perspective this is a tidy, narrow traffic profile: a sealed audit phase, then a gated confirmation phase with observable, well-defined requests against the target.
Installation follows the emerging skills pattern rather than a classic binary release: npx skills add adshao/flounder --skill flounder -g -a codex -a claude-code installs the skill globally for agent runtimes, and a local checkout variant (npx skills add .) is available for contributors. Once installed, a natural request like Audit this repository with Flounder triggers the skill, whose source of truth is skills/flounder/SKILL.md. That document-driven contract is worth reading before an engagement, since it defines exactly when the skill activates — audits, smart-contract or ZK review, daemon/provider setup, finding verification, and report collection.
Engagement modes and scenarios are a notable part of the product surface. The default standard posture covers general authorized review; bug-bounty records program scope, keeps live-target confirmation mandatory, and gates reporting on scope, novelty, known-issue, impact, and payout checks; bug-bounty-contest supports short settled batches with source-only confirmation when the venue rules allow it. A scenario table covers blind capability audits, incident investigation from suspicious on-chain clues, open-world public-source audits, contests, targeted follow-up via audit --verify or audit --scope, and disclosure preparation. The incident-investigation framing is notably careful: the clue is treated as evidence, not proof, and the output should explain the root cause and whether it reproduced on attacker-real local ground truth.
Coverage accounting is versioned and compositional. Scope inventories and model memory are bound to a fingerprint of the prepared material, so a re-run after target changes doesn't silently reuse stale scope. Independent Map inventories are unioned without dropping singleton scopes, every Dig writes a separate obligation and composition outcome, and incomplete outcomes stay visible rather than disappearing. For contest work, flounder preserves prior coverage and submitted findings with append-map expansion instead of remapping from scratch — the kind of durability detail that only surfaces when a tool has been used on multi-day engagements.
The execution architecture separates control plane from executor. The UI server is a React dashboard and self-describing REST API, while audits actually run on a daemon — optionally on a different machine — so target code and provider credentials stay on the executor host. flounder group runs validated positive, negative, control, replay, and multi-target work items through the same daemon queue, with concurrency, attempts, blocked setup, and evidence outcomes surviving control-plane restarts. Storage hygiene is visible too: the dashboard attributes run/history/workspace bytes to projects, finds orphaned timestamped runs, warns on low volume, and CLI cleanup is dry-run first and refuses active work.
A maintainer-facing flounder experiment mode exists, gated behind explicitly starting the control plane with flounder ui --maintainer. It mines verifier-grounded evaluation failures, constrains source proposals to an allowlist, and compares paired baseline/candidate runs, with promotion requiring distinct cases and bug families, passing hidden holdouts and controls, and no paired regressions — and merge/deployment remain human gates. Ordinary users never see it, which is a reasonable governance choice for anything that evolves its own audit behavior.
Where this fits for an authorized professional: flounder is strongest on Solidity/EVM targets, where local forks and Foundry/Hardhat tests can prove real on-chain effects, and on ZK proof systems, where local prover and constraint harnesses can turn subtle missing constraints into executable counterexamples. It suits bounty work inside sanctioned scopes, internal code review where you hold the rights to the target, and incident post-mortems starting from on-chain evidence. What to watch for: the framework's honesty depends on its evidence gates, so operators should audit SKILL.md and the command policy before pointing it at anything sensitive, keep the daemon host isolated, and remember that confirm-phase egress — however narrow — is still live traffic against the target, which belongs only in engagements you are explicitly authorized to run.
adshao/flounder.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.