Security guardrails and structured verification workflow for AI-built web applications.
TorusGuard is a Markdown-first, portable AI-agent skill and security workflow engine. It helps developers and AI coding agents audit, verify, harden, and re-check modern web applications through structured rules, normalized evidence schemas, and human-friendly remediation workflows across frontend database isolation, secrets management, input validation, authentication, rate limits, SSRF, webhooks, and production deployment safety.
AI code generators accelerate product development, but they can easily introduce critical security oversights—such as client-side database queries, exposed API secrets, missing authorization checks, or unvalidated outbound requests. Security decisions still require structure, boundaries, and systematic verification. TorusGuard gives AI coding agents the context, guardrails, and deterministic workflow needed to build and deploy securely.
If the browser receives it, users can inspect it.
DevTools, Inspect Element, and the Sources tab cannot be blocked. TorusGuard enforces that database credentials, sensitive business logic, and authorization decisions must always remain on trusted server-side code.
TorusGuard features a formal closed-loop state machine governing every candidate security finding:
┌───────────┐ ┌────────────┐ ┌───────────┐ ┌─────────────┐ ┌──────────┐ ┌───────────┐ ┌───────────┐
│ 1. Detect │ ──► │ 2.Classify │ ──► │ 3. Verify │ ──► │ 4.Remediate │ ──► │ 5. Apply │ ──► │ 6.Recheck │ ──► │ 7.Archive │
└───────────┘ └────────────┘ └───────────┘ └─────────────┘ └──────────┘ └───────────┘ └───────────┘
- Detect (
/torusguard audit): Scan repository source code, environment templates, and manifests. - Classify: Assign a canonical Rule ID (
TG-*), taxonomy category, risk severity, and initial confidence. - Verify (
/torusguard verify): Validate evidence sufficiency and reachable data flow. If evidence is ambiguous, force status toNeeds Review. - Remediate (
/torusguard harden): Formulate framework-native, least-invasive remediation plans and candidate diffs. - Apply (
/torusguard apply): Use the Ponytail engine to surgically apply minimal, bounded patches to target files. - Re-check (
/torusguard recheck): Re-audit modified code to verify that the vulnerability is resolved (Verified Fixed). - Archive: Preserve timestamped verification evidence and cryptographic hashes in the project audit record.
- Markdown-First & Agent-Portable: Works out-of-the-box in Cursor, Antigravity, Claude Code, Cline, Codex, Gemini CLI, and other agent environments without requiring external compilation or runtime daemons.
- Formal Data & Evidence Schemas (
schemas/): Strict JSON schemas for findings, evidence typing (source,runtime,test,manual_review), and remediation objects. - Repeatable Validation Harness (
harness/): Standalone automated test harness validating schemas, 60-rule catalog integrity, and differential fixture behavior. - Framework-Aware Security Catalog: 60+ structured security rules across secrets, database access, input validation, authentication, rate limits, SSRF, CSRF, webhooks, GraphQL, WebSockets, and supply chain.
- Multi-Ecosystem Support: Deep, framework-idiomatic guidance for JavaScript/TypeScript (Node.js, Express, React, Vite, Next.js) and Python (Django, DRF, FastAPI, Flask, SQLAlchemy).
- Human-First Findings: Generates clear, readable audit reports featuring severity levels, plain-English risk explanations, and concrete Before/After code snippets.
TorusGuard v0.5.6 introduces a structured validation architecture for large-scale, real-world repositories alongside context-aware rule tuning and honest readiness evaluation:
- 10 Large-Project Validation Architecture (
projects/manifest.yaml): Standardized multi-repository validation harness supporting real-world Python codebases (Django, Flask, FastAPI, SQLAlchemy, DRF, Sentry, Requests, Pydantic, Celery, Scrapy) totaling 14,000+ source files. - Rule Context Tuning & Guardrails: Hardened detection rules (
TG-AUTH-008,TG-INPUT-005,TG-INPUT-006,TG-DB-004) to distinguish safe framework mechanisms (e.g. auto-escaping, ORM tenant managers) and downgrade ambiguous contexts toNeeds Review. - Seeded-Case Recall Measurement: Integrated known synthetic vulnerability seeds across target repositories to ensure rule tuning preserves high recall without blind suppression.
- Ponytail Patch Quality Tracking: Structured ledger recording patch efficiency (files changed, line churn, excess comments, new risks, recheck outcomes).
- Honest Readiness Classification: Strict policy against unverified 100% metrics. Distinguishes simulated workflow runs from real repository triage with clear pilot readiness boundaries.
Read the complete release notes in docs/releases/v0.5.6.md and the portfolio report in docs/validation/v0.5.6-large-project-validation-report.md.
| Version | Focus / Key Feature | Summary of Deliverables |
|---|---|---|
| v0.5.0 | Workflow Architecture | 6-stage lifecycle, 10 formal JSON schemas, core engine. |
| v0.5.1 | Provenance & Confidence | Auditable 5-factor confidence scoring, SHA-256 evidence hashing. |
| v0.5.2 | Validation Engine | 3-pass deterministic replay, regression tracking, FP analyzer. |
| v0.5.3 | Python Parity | Native coverage for Django/FastAPI/Flask/SQLAlchemy rules. |
| v0.5.4 | Usability & Reporting | 9-section reports, remediation triage, sensitive data masking. |
| v0.5.5 | Execution & Safety | RunFolder isolation, Ponytail agent integration, /torusguard apply. |
| v0.5.6 | Large-Project Validation | 10-repo validation suite, context rule tuning, seeded recall, honest readiness. |
- Django Guide — Settings, CSRF, ORM queries, ModelForms, object ownership.
- Django REST Framework Guide — Default permissions, ViewSets, serializers, throttles, pagination.
- FastAPI Guide — Pydantic v2 schemas, dependencies, outbound SSRF checks, HMAC webhooks.
- Flask Guide — Factory setup, session cookies, CSRFProtect, Werkzeug upload boundaries.
- SQLAlchemy Guide — Parameterized
text()bindings, query scoping, update allowlists. - Python Dependencies & CI/CD — Reproducible lockfiles,
pip-audit, GitHub Actions pinning. - Python Rule Mapping Matrix — Framework implementation matrix for universal rule IDs.
- React + Vite Guide — Frontend environment variables, build artifact leakage, source maps.
- Next.js Guide — App Router / Pages Router security, Server Components, API routes.
- Node.js + Express Guide — Middleware hardening, CORS, Helmet, session cookies, rate limiting.
- Supabase Guide — Row-Level Security (RLS), service role key isolation, database policies.
- Firebase Guide — Firestore Security Rules, client SDK boundaries, privileged admin tasks.
Install TorusGuard into your AI coding tool using the open skills CLI:
npx skills add https://github.com/githubmofo/TorusGuard --skill "torusguard"| Command | Lifecycle Phase | Purpose | Modifies Code? |
|---|---|---|---|
/torusguard init |
Baseline | Generates a project SECURITY.md, threat model, and baseline. |
❌ Docs only |
/torusguard audit |
Detect & Classify | Scans repository against TorusGuard rules and outputs a structured report. | ❌ No |
/torusguard verify |
Verify | Validates evidence sufficiency and checks manual review criteria. | ❌ No |
/torusguard harden |
Remediate | Formulates framework-native remediation guides and candidate diffs. | ❌ No (Plan only) |
/torusguard apply |
Apply | Uses the Ponytail engine to surgically apply minimal, safe patches. | ✅ Yes |
/torusguard recheck |
Re-check | Re-evaluates post-fix code to assert resolution (Verified Safe). |
❌ No |
When an audit report is generated:
- Inspect Evidence Snippet: Confirm the cited file path and line numbers exist in your active codebase.
- Review Confidence Classification:
Confirmed: Proved with direct source code or configuration evidence.Needs Review: Requires verifying out-of-band context (e.g. domain service layer, upstream API gateway, cloud IAM).
- Execute Verification Command: Run the documented test command in the finding's
Verificationsection.
- Formulate the Fix: Run
/torusguard hardento generate candidate diffs and remediation guides in.torusguard/runs/.../remediation.md. - Apply via Ponytail: Run
/torusguard applyto let the Ponytail engine apply minimal, bounded patches without touching unrelated code. - Run Differential Re-check: Execute
/torusguard recheckto verify that the finding transitions toVerified Safe.
TorusGuard maintains repeatable automated validation harnesses:
# Core validation suite (schemas, rules, differential fixtures)
python harness/runner.py
# Large-project validation harness (multi-repo validation & recall benchmarking)
python harness/validate_large_projects.py projects/manifest.yamlThe harness suite verifies:
- Schema Validation: Verifies all schemas in
schemas/. - Rule Catalog Integrity: Validates 60+ unique
TG-*rule IDs with 0 duplicates. - Differential Fixtures: Tests vulnerable vs hardened pairs in
examples/python/. - Stack Detection Fixtures: Tests 7 repository layouts in
tests/fixtures/python/stack-detection/. - Regression Suite: Executes paired Python regression fixtures in
tests/fixtures/python/. - Large-Project Profiles: Tests 10 major repository profiles in
projects/manifest.yaml. - Lifecycle Assertions: Validates state machine transitions.
Read the complete validation summary in docs/validation/README.md.
To maintain technical honesty and clear boundaries:
- Not an automated vulnerability scanner: TorusGuard is a contextual guidance framework for developers and AI agents. It does not replace dynamic application security testing (DAST) or static binary analyzers.
- Not a penetration-testing replacement: It elevates baseline security hygiene but cannot replace authorized professional penetration testing.
- Not an "unhackable" guarantee: No tool can guarantee 100% security.
- Not a client-side DRM: Browser-delivered JavaScript cannot be hidden from DevTools; security must reside on the backend.
TorusGuard/
├── schemas/ # Formal JSON schemas (finding, evidence, remediation, rule, lifecycle)
├── core/ # Core workflow models, lifecycle state machine, and formatter
├── harness/ # Repeatable validation runner & large-project validation harness
├── projects/ # Multi-repository validation manifest and seeded-case definitions
├── skills/TorusGuard/ # Portable skill instructions and reference modules
├── rules/ # 60+ documented security rules across 9 lifecycle categories
├── templates/ # Standardized templates (SECURITY, audit, pre-flight)
├── guides/ # Stack-specific implementation guides (Node.js & Python)
├── examples/ # Educational vulnerable & hardened reference applications
├── docs/
│ ├── architecture/ # Architecture specifications (v0.5.0, v0.5.4, v0.5.6)
│ ├── workflow/ # Finding lifecycle and verification guides
│ ├── releases/ # Release notes (v0.2.0 - v0.5.6)
│ ├── python-rule-mapping.md # Universal rule mapping across Python stacks
│ ├── validation/ # Official validation reports & large-project portfolios
│ └── roadmap.md # Project roadmap & milestones
└── tests/ # Test fixtures and regression test suites
Contributions are welcome! Please review CONTRIBUTING.md and our Code of Conduct before submitting an issue or pull request.
Please review our Security Policy for private responsible disclosure instructions. Do not file public GitHub issues for security vulnerabilities.
TorusGuard is licensed under the MIT License.
Copyright (c) 2026 Jenish Lad.