Audit your own repo with the security-audit skill in free-pi

free-pi bundles the audit method and reference checklists from Cloudflare's open-source security-audit skill, so you can ask your terminal agent for a structured security review of a repository you own. This guide explains what the skill's method is, how to start it, and how to check what comes back. We build free-pi, so read this with that in mind.

Only audit code you own or have written permission to test. That includes your own projects, your employer's code when you have permission, and targets that are in scope for a bug bounty program.

What the skill is

The skill comes from the cloudflare/security-audit-skill repository (https://github.com/cloudflare/security-audit-skill) and uses the MIT license. Its README describes a six-phase method:

1. Reconnaissance. Map architecture, trust boundaries and input surfaces, and write them to architecture.md and coverage-ledger.json.
2. Coverage-led hunting. Work through units from the coverage ledger and look for weaknesses.
3. Candidate validation. Try to disprove each unique candidate before accepting it.
4. Structured output. Write results to findings.json as confirmed, needs_validation or rejected, checked against a JSON schema.
5. Record verification. Re-check the source claims in the final records.
6. Reporting. Derive REPORT.md, FINDINGS-DETAIL.md and NEEDS-VALIDATION.md from the records.

The skill also ships reference files with attack classes for specific kinds of targets, such as web and auth protocols, client-side code, supply chain and release, cloud deployment, and memory safety.

How free-pi runs it

The skill's own README is written for a setup that has two things free-pi does not have. It expects a coding agent that can run parallel sub-agents, so that the agent that finds a problem is never the agent that checks it. It also expects an operating-system sandbox with no external networking for running any code from the target.

free-pi runs the skill in a single agent, without sub-agents and without an OS sandbox. The agent follows the method itself, one step after another. That has two consequences you should plan for:

• The independent checking that the skill's design describes does not happen. The same agent that raises a candidate also judges it. Validate each finding yourself before you act on it.
• Do not ask the agent to build or run code from a repository you do not trust. Review the code instead.

What you need

• free-pi, started with npx free-pi-cli and signed in with GitHub.
• Node.js, which the skill's two validator scripts need.
• A repository you are allowed to audit.

Start a review

Start free-pi from the root of your repository and describe the job in plain words. The skill's README gives these examples:

security audit this codebase

find security vulnerabilities in ./src

do a security review, output to ~/audits/my-project

A direct request to audit a codebase asks for the full method. A narrower security question gets lighter guidance, and the skill does not write report files unless you ask for them. If you do not name an output directory, the skill's default is ~/security-audit-skill/<repo-name>/run-<N>, outside your repository. If you pick a directory inside the repository, make sure version control ignores it.

Check the results yourself

Open REPORT.md first if the run wrote one. Then work through the records by verdict:

• confirmed: the record should have a source trace. Follow it in the code yourself, and try to explain why the code is safe before you accept that it is not.
• needs_validation: each one should name the exact fact that is still unknown. Often you can answer it in a minute because you know your own deployment.
• rejected: skim these. They show what the agent considered and set aside.

The skill's authors say a single run found roughly half of the vulnerabilities that repeated runs found in total. Plan to run it more than once, for example after you fix the first batch.

Where the Defense section fits

If a general model stops partway through and refuses lawful work on your own code, you can switch models with /model and look for the Defense section. See the companion post on using the Defense section responsibly. The skill's method works with whichever model you select.

Limits

An AI review does not replace a human review, a penetration test, or a bug bounty program. The agent reads code. It cannot see your cloud settings, your registry permissions or your branch protection rules. Treat every finding as a lead you must verify.