# Flounder

> An autonomous white-hat security auditor.

Flounder turns skills-aware coding agents into an execution-backed white-hat
security audit workflow. Install the skill once, then ask Codex, Claude Code,
Gemini CLI, Cursor, OpenCode, OpenHands, or another compatible agent to audit
an authorized target.

## Primary Links

- Website: https://flounders.xyz/
- Source: https://github.com/adshao/flounder
- Usage: https://github.com/adshao/flounder/blob/main/docs/USAGE.md
- Architecture: https://github.com/adshao/flounder/blob/main/docs/ARCHITECTURE.md
- Security policy: https://github.com/adshao/flounder/blob/main/SECURITY.md
- License: AGPL v3

## Install

```bash
npx skills add adshao/flounder -g
```

## Product Summary

Flounder supplies the sandbox, command policy, durable state, execution gates,
daemon control plane, local dashboard, REST API, and reports. The agent prepares
the target, audits source, constructs exploit paths, runs local proof tests, and
collects execution-backed bug report packages.

## Use Cases

- Blind capability audits from an authorized project, repo, package, source tree, or project link with no bug hint.
- Incident investigation from a suspicious transaction, address, exploit link, or factual clue.
- Open-world bounty audits with official docs, scope, deployments, provenance, and package metadata.
- Source-provided audits when code is already staged with source paths, build root, and optional corpus.
- Targeted follow-up for suspected findings, scope ids, file regions, or prior runs.
- Disclosure preparation for confirmed or reproduced findings with reports, decisions, and command evidence.

## Safety Boundary

Use Flounder only for authorized audits or public bug-bounty scope. Discovery is
network-sealed. Confirmation must never broadcast transactions, move funds, or
write to live systems.

## FAQ

- Flounder is local-first: the dashboard/control plane runs on localhost by default, and audits execute on a daemon the operator controls.
- Flounder is open source under GNU AGPL v3.
- The recommended interface is the Flounder skill: install it once, then ask Codex, Claude Code, or another skills-aware agent to audit, verify, confirm, or collect a report.
- Flounder is not a scanner. The agent owns audit strategy; Flounder supplies sandboxing, command policy, durable state, execution gates, daemon control, and reports.
- Serious audits can be token-heavy. Budgets can be capped, but the default unbounded run gives the agent the best chance to finish and can resume after interruption.
- Target code, provider credentials, artifacts, and workspaces stay under local control. The selected model provider still receives the context the agent sends.
- Real audits need Node.js 24.13+ on the current 24 LTS line, a skills-aware agent, the Flounder skill, daemon provider auth, and a Docker/OCI sandbox image or an explicit trusted host mode.
- Flounder is a strong fit when claims can be proven locally: repositories, packages, Solidity/EVM, ZK/proof systems, suspected findings, transactions, addresses, and prior reports.
- Use Flounder only for authorized targets. Confirmation can read/fork/search, but must never broadcast, move funds, submit writes, persist access, or go outside scope.