SecHelix

[SecHelix — evidence-first application security for coding agents]

Most AI security tools try to find more. SecHelix tries to prove itself wrong.

[validation] [Apache-2.0]

SecHelix

Every candidate finding goes to an independent verifier whose only job is to disprove it. The report shows you what it refuted and why — and returns INCOMPLETE rather than a clean PASS when it could not actually check.

Open source, Apache-2.0, for code you own or are authorized to test. Runs in Claude Code, Codex, Copilot and other Agent Skills-compatible agents; the Python runtime is optional.

It helps a coding agent:

• map the attack surface and trust boundaries;
• review only security checks that apply to the project;
• investigate authentication, authorization, business logic, injection, SSRF, files, supply chain, AI/MCP and other security surfaces;
• verify important candidates instead of reporting guesses;
• fix the root cause;
• add regression proof and retest;
• return a clear release decision.

See it work in 90 seconds

git clone https://github.com/omarmohelal/SecHelix && cd SecHelixpython examples/expense-api/prove.py

A small multi-tenant API with two candidate issues. One is a real cross-tenant read that a scanner walks past, because the endpoint does have an authorization check — it just checks the wrong thing. The other is f-string SQL that every pattern matcher flags and that is not exploitable at all.

Walkthrough, root cause, the two-line fix and the regression proof: examples/expense-api.

Or take the same test in your browser — ten cases, three of them decoys, no signup: Can you tell the real bug from the decoy?

Install

Recommended for Agent Skills-compatible coding agents:

npx skills@latest add omarmohelal/SecHelix --skill sechelix

Then open the repository you want to review in your coding agent. The skill installs instructions and data only — no executable code. The optional runtime below is a separate, explicit install.

A compact edition, sechelix-lite, is a single runtime-free review skill (about 200 lines plus five references) for skill directories and hosts where a small context footprint matters. See docs/distribution/awesome-copilot.md.

Use it

Full security audit

Copy this into your agent:

Use SecHelix for a complete authorized security audit of this repository.Start STATIC and use LOCAL only if it is safe and useful.Map the attack surface and trust boundaries first.Verify important candidates before reporting them.Fix root causes, add regression tests, retest, and give me the final release gate.

Fast security review

Use SecHelix to triage this repository for security issues.Prioritize authentication, authorization, business logic, secrets, injection, SSRF, file handling, supply chain, dangerous configuration, and AI/MCP surfaces.Return evidence-backed findings and clearly mark anything unproven.

AI-built app launch audit

Use this before launching an AI-generated, agent-generated, rapidly prototyped, or vibe-coded application:

Use SecHelix's AI-Built App Launch Audit on this authorized application.Evaluate launch checks 01-36 from references/ai-built-app-launch.md.Do not mark PASS without exact code, configuration, policy, test, log, or safe runtime evidence.For every FAIL or security-relevant UNKNOWN, give the realistic failure mode, smallest root-cause fix, and exact safe verification step.After fixes, re-run the failed/unknown checks and produce the normal SecHelix release gate.

The launch profile covers practical pre-release failures around secrets, auth/authz, cross-user data, database/storage permissions, debug exposure, input validation, SQL/NoSQL injection, XSS/CSRF, uploads, traversal, SSRF, password reset, sessions/JWT, CORS, rate limiting, staging, default credentials, webhooks, payments/entitlements, IDOR/BOLA, sensitive logs, and production artifacts.

Review a pull request

Review this PR with SecHelix.Focus on security changes introduced by the diff, verify important candidates, and tell me whether the PR introduces a verified blocker or known risk.

Fix findings

Use SecHelix Fix Mode on the verified findings.Fix the root cause, look for variants of the same bug, add security regression tests, and retest the original finding.

More copy-paste workflows: Command Cookbook.

What should I ask SecHelix to do?

You do not need to memorize special slash commands. SecHelix is primarily a skill: tell the coding agent what security job you want done.

How the review works

scope  → map attack surface  → select applicable checks  → investigate  → independently verify important candidates  → fix root cause  → add regression proof  → retest  → report + release gate

A scanner match or model suspicion is treated as a candidate, not automatically as a vulnerability.

A strong finding should show the affected surface, attacker control or security boundary involved, reachability, impact, root cause, safe evidence, the fix, and regression/retest status.

What SecHelix does not claim

• It is not a certification. PASS means the release-gate rules found no unresolved blocking condition in what was reviewed, not that the software has no vulnerabilities.
• On real code it found 2 of 12 known CVEs. A blinded run against the vulnerable and patched trees of 12 recent CVEs found 2 cleanly under the pre-registered rule, 3 with hand adjudication, and no finding it marked VERIFIED was one of the known defects (report). Precision is NOT_MEASURED.
• The model still does the reasoning. SecHelix structures the review and labels unproven claims as unproven rather than dropping them: in that run 92 of 106 findings were marked LIKELY_BUT_UNPROVEN or HYPOTHESIS. It does not make a model see a bug it cannot reason about.
• Host support varies. Installation is verified for the Claude Code plugin, the Agent Skills CLI, the portable bundle and the curated Copilot CLI plugin; other hosts are documented paths (compatibility).
• Authorized targets only. It is not an internet scanner and ships no exploit payloads.

Full local runtime: SecHelix + embedded Strix

For the complete local stack, including the exact Strix source revision that SecHelix has compatibility-tested, clone with submodules and run the bootstrap:

git clone --recurse-submodules https://github.com/omarmohelal/SecHelix.gitcd SecHelixbash scripts/bootstrap-full.sh

This materializes Strix under engines/strix inside the SecHelix checkout and installs both projects into one Python 3.12 virtual environment. The source is embedded for reproducible installation, while the SecHelix adapter remains the authorization/evidence boundary. OpenRouter setup and first-run commands are in docs/full-install.md.

Optional CLI runtime

The Agent Skill works without the Python runtime. The runtime is optional and adds stored runs, coverage tracking, replayable evidence, reports, CI-friendly exit codes, and an MCP adapter.

Install it with:

pipx install sechelixsechelix doctor

uv tool install sechelix and python -m pip install sechelix are also supported.

Useful CLI commands

Example:

sechelix doctorsechelix audit . --executor claude-codesechelix launch-audit . --executor claude-codesechelix coveragesechelix report --format markdown

sechelix audit . with the default --executor none intentionally does not pretend to analyze code. Reasoning nodes are blocked and the run remains incomplete until a real executor is configured.

Audit and launch-audit runs now write a self-sealed node-boundary checkpoint under .sechelix/checkpoints/ by default. If the process or host dies, pass that file to --resume-from; completed node evidence is kept, remaining nodes can use a different executor/provider, and resume fails closed if the target commit, scope, graph, input world, budget limits, or checkpoint digest changed.

For all CLI flags:

sechelix --helpsechelix audit --help

Advanced runtime guide: V4 Runtime Quickstart.

GitHub Action

- uses: omarmohelal/[email protected]  with:    executor: none

Outputs PASS, PASS_WITH_KNOWN_RISK, BLOCKED or INCOMPLETE, writes SARIF for code scanning, and uploads the run as an artifact. The default executor: none deliberately reports INCOMPLETE rather than a green check it did not earn — configure a reasoning executor to get an actual review.

Full reference: GitHub Action.

MCP adapter

uvx sechelix mcp /path/to/the/repository

Seven tools over a root you choose, no shell, no network. Six only read; sechelix_audit writes only a run workspace inside that root. The root is the security boundary: point it at the repository under review, not at your home directory.

Reference: MCP adapter.

Execution modes

Only test systems you own or are explicitly authorized to assess. See SECURITY.md.

Output

Depending on the workflow and available runtime, SecHelix can produce:

• evidence-backed findings and refuted candidates;
• root-cause remediation guidance or fixes;
• security regression tests;
• retest status;
• Markdown, redacted JSON, SARIF or HTML reports;
• a release decision: PASS, PASS_WITH_KNOWN_RISK, BLOCKED, or INCOMPLETE.

Documentation

Start with the practical docs and use the deeper material only when you need it:

• Command Cookbook — copy-paste security workflows.
• AI-Built App Launch Audit — evidence-gated pre-launch checks for AI-built/vibe-coded apps.
• V4 Runtime Quickstart — optional CLI/runtime usage.
• GitHub Action — SecHelix in GitHub Actions.
• MCP adapter — the local MCP server surface.
• CI Integration — using SecHelix in CI.
• Architecture — design and internals.
• Evaluation — evaluation methodology and results.
• Extensions — extending the framework.
• SEO Audit and Codebase Cleanup — optional, explicitly requested quality workflows with their own reports (prompts); not part of the security verdict.
• Security Policy — safe use and vulnerability reporting.
• Contributing — contributing to SecHelix.

The repository also contains detailed schemas, catalogs, adapters, evaluation fixtures and research material. They support the framework; you do not need to read them to start using SecHelix.

License

Apache-2.0. See LICENSE.