secure-tdd-agent-framework - Test-Driven Development agent framework with integ

项目说明

Secure TDD Agent Framework

> A TDD and QA framework with integrated security for AI coding agents and de. Combines functional test-first engineering, living STRIDE threat modeling, local code quality checks, and continuous skill self-e to mitigate recurring issues.

> [!CAUTION]
> Use at Your Own Risk: This repository is a demonstration of an approach, not an officially supported framework. AI coding agents generate and execute code that may be unstable or perform unexpected actions. While this approach works to mitigate these very problems through test-first boundaries and local scanning, no testing framework offers a complete solution to model error. Run agentic workflows only in isolated de en and never on systems with access to production credentials, sensiti data, or internal networks.

---

1. Security as Part of Quality

Test-Dri (TDD) writes tests first to encode the requirements early on and target de against discrete goals. It documents expected behavior, catches regressions early, and keeps the agent zeroed in on implementing logic instead of guessing. This reduces some of the common issues with AI generated code, for example hallucinated features, hallucinations on test co, and going off on sidequests to recreate entire helper libraries, which is a nightmare to even run agentic reviews against.

Historically, software engineering has often treated functional QA and security testing as completely separate disciplines:

QA runs during de and CI to business logic, user journeys, and regressions.

Security is siloed into delayed post-merge scans or third-party audits (leading to an a 20-day remediation cycle, deliterious impacts to throughput, and high context-switching costs). With AI agents, this old approach may lead to more growth risk than the security risk it mitigates, and it certainly costs more to fix later than the moment the code is written.

The Flaw with Re ONLY in CI/CD

When security and QA reviews happen only downstream in CI/CD or post-merge pipelines:

Delayed Discovery: De recei hours, days, or weeks after authoring code, when the architectural context is no longer fresh.

Context-Switching Tax: Fixing a failure detected in CI requires rolling back branches, reopening pull requests, and context switching away from current feature work.

Compounding Technical Debt: AI coding agents without local QA guardrails generate unchecked assumptions and subtle logic bypasses that escape into the codebase.

Security as Part of Software Quality (and the Stability Risk of Isolation)

Security is an intrinsic part of software quality. Treating security separately from functional de introduces direct risks to system stability:

Isolated Security Threatens Stability: When security is treated in isolation from functional de, it actively poses a risk to system stability. Out-of-band security scans, external remediation workflows, or isolated security patches frequently introduce regressions, break existing API contracts, and cause unexpected production outages because they modify code without context of the application's functional requirements.

Co- via TDD: Security patches that break functional behavior introduce regressions into production. Unifying security constraints with TDD codifies defensi (authentication, input allow-lists, parameterized sinks) into tests alongside functional acceptance criteria (happy paths, business workflows). This supports preserving both security and operational stability.

The Inner-Loop Ad: Moving threat modeling and security test assertions into the de's local test-first loop (TDD) eliminates issues in seconds while code is actively being written.

Secure TDD brings security into e QA and TDD workflows:
1. Holistic Planning & Threat Modeling: Features are planned with both functional user stories and STRIDE boundary constraints *before* code is authored.
2. Comprehensi (RED): Unit and integration tests assert both functional outcomes (HTTP 200/302, correct payloads) and defensi (HTTP 400/401/403, input rejections).
3. Clean, Defensi (GREEN): Minimal, maintainable production code satisfies functional specifications while using safe design patterns (allow-lists, parameterized queries, least pri).
4. Local Refactoring & Deterministic Scanning (REFACTOR): Fast local checks (linting, test suite regression passes, secret detection, Semgrep SAST) code quality before commits.
5. Continuous Quality & Security E: When edge cases, bugs, or security patterns are resolved, the framework captures the lesson into CONTEXT.md and SKILL.md so the entire team and agent fleet learn permanently.
6. No Hea Required: All state is managed transparently Markdown (CONTEXT.md, threat_model.md) and append-only logs (.security-gate/).

> [!TIP]
> Living Exemplar (Dogfooded in this Repository): We use this exact Secure TDD workflow to update and maintain this framework itself! Readers can inspect the live threat_model.md generated during Phase A (which models the framework's own pre-push hook gates and trust boundaries) and the comprehensive test co across tests/ and .agents/tests/ written test-first during Phase B as real, working examples.

---

2. Inspiration, CI/CD Balance & Scaling Philosophy

This framework brings together two inspirations:
1. TDD & Continuous : Drawing on the engineering discipline of TDD and Paul Hammond's pioneering work where rapid feedback loops, high confidence, and test-first design enable de to ship reliably and move fast.
2. Modular Agent Skill Architectures: Inspired by research into agentic reasoning and specialized skill structures, including Google's Mantis project.

Standalone Security Agents De

Dedicated security review engines like Google Mantis serve as powerful standalone security re—performing deep offline batch sweeps, multi-repository research, and exploit reproduction in isolated en.

Deeper Security Belongs in CI/CD: Exhausti (fuzzing, dynamic analysis, complex multi-repo exploit research, and whole-dependency graphing) should still take place in CI/CD.

CI/CD as a Secondary Safety Backstop: CI/CD functions as a safety backstop for long-running checks, while the inner-loop framework eliminates functional flaws and security findings locally during acti.

Solo De to Teams & Centralized Architectures

Out of the Box for Solo De:

- Designed to work seamlessly with zero infrastructure: all context lives in human-readable Markdown (CONTEXT.md, threat_model.md), and local deterministic pre-push hooks run offline.
- The de maintains full into all changes. In this local setup, the coding agent can "self-heal" by updating local SKILL.md files directly when new con or edge cases are resolved.

Scaling to Larger Teams & Enterprise:

- For larger engineering teams, threat models and skills can scale across services via a centralized knowledge base and shared skill registry.
- Go on Skill E: In a team or enterprise en, indi coding agents should not ha to directly mutate skills in a shared registry. Instead, the agent's continuous e phase can be configured to submit *suggested skill impro, PR proposals, or ticket drafts* for review by QA and security leads.

Extensible by Design: The framework is intentionally unopinionated and modular—it works effortlessly out of the box for an indi de, while pro clear extension points to integrate with centralized registries, team knowledge bases, and enterprise CI/CD systems.

Design Principles:

1. De Inner-Loop Integration: Plugs directly into e de tools (git, pytest, unittest, local linters) without requiring hea infrastructure or out-of-band audit cycles.
2. Modular & Extensible Skills: Skills are loosely coupled and self-contained in standard SKILL.md packages. De can freely adopt, customize, or extend whiche suit their project (e.g. adding custom domain linters, specialized QA runbooks, or tailored threat models).
3. Multi-Agent Portability: Built on open agent skill standards (standard YAML frontmatter and Markdown), allowing identical skills to run seamlessly across Antigravity, Claude Code, and other coding assistants.
4. Zero-Database Transparency: All architectural state and security context li alongside the code in human-readable Markdown (CONTEXT.md, threat_model.md) and append-only logs (.security-gate/).

---

3. The Secure TDD Inner-Loop

Phase-by-Phase Breakdown

#### Phase A: Planning, Functional Scoping & Threat Modeling (Plan Phase)

Core Skill: threat_model_assessor

Ingests CONTEXT.md to identify existing trust boundaries, data flows, and appro.

Decomposes the feature into clear functional deli and e STRIDE risks (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Ele of Pri).

Generates or updates threat_model.md at the workspace root, establishing both Functional and Security Acceptance Criteria.

#### Phase B: Functional & Security Test-First Case Creation (Red Phase)

Core Skill: security_test_writer

Authors comprehensive test cases co:

1. *Functional Acceptance*: Happy paths, business logic workflows, valid outputs (e.g. HTTP 200/302).
2. *Edge Cases & Error Handling*: Malformed inputs, missing parameters, out-of-range .
3. *Security Boundary Enforcement*: Rejecting unauthenticated requests, unauthorized access, path tra, injection payloads (e.g. HTTP 400/401/403).

Adheres to the Three Pillars:

1. *Beha HTTP/API outcomes*: Assert strictly on observable contracts and status codes.
2. *Strict test isolation*: Fresh contexts and transaction rollbacks.
3. *Integration o mocking*: Local test instances instead of superficial fakes.

Runs the test suite and confirms tests fail for the expected reason (RED).

#### Phase C: Clean Defensi (Green Phase)

Core Skill: defensi

Authors the minimal, high-quality production code required to satisfy all failing tests.

Adheres to the Three Defensi:

1. *Strict input *: Type safety, structured schemas (pydantic), and allow-lists o regex.
2. *Explicit authorization*: Caller identity and permission before executing logic.
3. *Least pri & safe sinks*: Parameterized queries, canonical path checking, and minimal returned data payloads.

Re-runs the test suite to confirm e is passing (GREEN).

#### Phase D: Refactoring, Quality, Context & Continuous E (Refactor Phase)

Core Skills: local_refactor_scanner, skill_e

Refactor & Context E: Along with code cleanup, the Refactor phase updates local project context and e skills to mitigate recurring bugs and security findings:

1. *Code Cleanliness & Maintainability*: Eliminate duplication, impro, and 100% passing test regressions.
2. *Local Scans & Guided Review*: Fast deterministic checks on changed files (secrets, dependency CVEs, local Semgrep SAST) + guided AI review to architectural boundaries.
3. *Update Local Context (CONTEXT.md)*: Extract systemic lessons, appro, and newly established con, appending them directly to CONTEXT.md under ## 4. Continuous E: Auto-E Con.
4. *Evolve & Suggest Skill Updates (SKILL.md)*: If a recurring anti-pattern, tricky edge case, or specialized QA/security workflow was identified, suggest or apply updates to SKILL.md instructions so future AI agent sessions inherit the rule upfront and avoid repeating the mistake.

##### Security Gate Hook Flow (Sequential Pipeline & Loop)

> TDD Principles & Continuous E in Hook Remediation:
> Every automated fix follows the TDD cycle rather than applying isolated code patches:
> 1. Add Boundary Test First (RED): A test case reproducing the finding or boundary constraint is added to the test suite and confirmed failing.
> 2. Apply Minimal Fix (GREEN): The defensive code change is applied to satisfy the failing test.
> 3. Full Suite Regression : The complete test suite is executed across all existing unit and integration tests to confirm that existing functionality is preserved and regressions are caught early.
> 4. Cross-Stage Context Import: Fixes applied during the Stage 1 deterministic scan are imported into Stage 2 so the contextual AI engine them against semantic constraints. If a Stage 1 fix cannot pass tests within 3 attempts, the unresol is imported directly into Stage 2 for multi-file contextual remediation.
> 5. Detailed Commit Documentation: Auto-commits include structured commit bodies detailing why the security test was added, the threat model boundary addressed, the fix implemented, and test passing confirmation.
> 6. Local Context & Skill E: When enabled, the hook appends newly con directly to the directory-level CONTEXT.md and outputs actionable suggestions for updating relevant SKILL.md files so future agent sessions avoid repeating the issue.

Optional Scanner Engines & Installation

The security gate hook supports modular scanning engines. Both scanners are optional:

Automatic Engine Detection: The hook checks which tools are a on your system PATH.

Graceful Execution: If semgrep is not installed, the pipeline skips Stage 1 and proceeds directly to Stage 2 (cm). If neither scanner is installed, the hook logs an informational notice and allows the push to proceed normally.

Designed for Extension: The engine architecture in .agents/lib/ is structured so teams can integrate alternati down the road (such as Wiz Code or Semgrep Pro for Stage 1, or custom engines for Stage 2).

#### 1. Semgrep (Stage 1: Open-Source Deterministic AST Scanner)
Semgrep runs fast local pattern checks against open-source rules without sending code off your machine.

Installation:

#### 2. CodeMender CLI (cm - Stage 2: Semantic Analysis & Remediation)
CodeMender provides semantic code analysis and multi-file contextual auto-remediation.

Installation & Setup:
1. Authenticate with Google Cloud:

2. Download the cm binary for your platform:

3. Extract and place on PATH:

4. Initialize your project:

---

4. Single Source of Truth & Downstream Distributions

This repository (secure-tdd-agent-framework) serves as the canonical upstream single source of truth for all skills, rules, threat models, and hook scripts.

Instead of maintaining redundant duplicate folders, the framework automatically builds and synchronizes dedicated downstream distributions:

Downstream Distribution Repositories:

secure-tdd-antigravity: Dedicated Antigravity workspace package containing .agents/, AGENTS.md, and CONTEXT.md.

secure-tdd-claude-code: Dedicated Claude Code CLI package containing .claude/ (with kebab-case skills and bash hooks), CLAUDE.md, and CONTEXT.md.

Platform Rule & Workflow Mapping

Different AI coding platforms disco instructions through different file locations. The canonical upstream repository maintains each format, and sync_downstream.py distributes them cleanly to their nati:

| Platform | Rule / Workflow Location | Purpose & Discovery Mechanism |
| :--- | :--- | :--- |
| Antigravity | .agents/rules/secure_tdd_workflow.md | Auto-discovered from .agents/rules/ with trigger: always_on. |
| Claude Code | CLAUDE.md (Project Root) | Auto-loaded by Claude Code on session start as the project system prompt. |
| Uni Agents | AGENTS.md (Project Root) | Uni reference document for any AI coding assistant or de. |
| Shared Context | CONTEXT.md & threat_model.md | Living architectural boundaries, helpers, and STRIDE acceptance criteria. |

---

5. Primary Use Cases & Operational Scenarios

1. Solo Original Feature De

When building new software or greenfield features as a solo de, you retain direct control o layer of the de cycle:

Direct Skill & Rule Customization: You can edit SKILL.md instructions, add custom domain helpers to CONTEXT.md, and configure your own test commands without needing approval from a centralized committee.

Platform Choice: You can operate natively in Antigravity or in Claude Code CLI depending on your preferred de workflow.

Observable Iteration: You see every test failure (RED), implementation change (GREEN), and refactoring step in your local en before code is pushed to remotes.

2. Autonomous Remediation & Automated Patching Agents

Automated security agents that ingest findings from external scanners (e.g. PR checks or pipeline notifications) benefit from specific skills in this framework:

Applicable Skills:

- security_test_writer: Translates a finding into an explicit, reproducing test asserting the boundary constraint before touching code.
- defensi: Applies minimal code modifications using established helpers and parameterization to satisfy the test.
- local_refactor_scanner: Executes the full local regression test suite to confirm existing functional behavior is preserved.

Operating Without Upfront Threat Models: An automated patching agent often receives an isolated finding report without a complete architectural threat model. To avoid applying blind patches that break production behavior, the agent uses the repository's CONTEXT.md as its primary reference:

1. *Context Reference*: The agent reads appro, trust boundaries, and coding con from CONTEXT.md.
2. *Synthesizing Scanner Output with Application Logic*: The agent matches the finding against existing route handlers and data schemas.
3. *TDD Guardrail*: By requiring a failing test first and a 100% passing regression run after, the agent that the patch resolves the finding without breaking existing API contracts.

3. Analyzing & Remediating Legacy Codebases

Applying automated security patches directly to legacy repositories with sparse or missing tests is risky. Modifying legacy code without functional test co often causes unexpected runtime regressions and breaks downstream consumers.

Recommended Remediation Sequence for Legacy Applications:
1. Initial Hotspot Triage: Run dedicated scanning and review tools like Mantis or CodeMender to identify high-risk components and compile an in of findings.
2. Establish Baseline Functional Test Co: Before modifying application logic, generate functional characterization tests for the target component until all existing paths pass green.
- *Example Prompt for Coding Agent*:
> "Analyze [target_module.py] and its callers. Write characterization unit and integration tests co the existing happy paths, parameter handling, and return contracts. Confirm all tests pass green against current behavior before applying any security modifications."
3. Incremental Secure TDD Fixes: Once baseline functional tests are passing green, address security findings one by one: write a reproducing boundary test (RED), apply the defensive fix using appro (GREEN), and confirm all existing legacy tests continue to pass.

---

6. Roadmap & Future Capabilities

Expanded LLM Engines: Multi-model routing supporting OpenAI Codex and diverse inference backends for skill execution.

Wiz Code Integration: Adding Wiz Code as an alternati 1 deterministic scanning engine alongside open-source Semgrep.

Language-Specific Skill Packs: Dedicated defensi and test writers for Go, Python, TypeScript/Node.js, Rust, and Ja.

Infrastructure as Code (IaC) : Extending test-first security to Terraform and OpenTofu modules, asserting IAM least pri, network egress boundaries, and resource policies through local policy-as-code tests.

Google Cloud Skill Modules: Using Google's pre-packaged skills for Cloud Run, Cloud KMS, Workload Identity Federation, and Secret Manager safe integration patterns.

---

7. Automated Downstream Synchronization

Whene are made to skills, rules, or hook scripts in this repository, the downstream repositories are updated automatically:

1. Manual / Scripted Sync

2. Local Git post-commit Hook

A local git hook is configured in .git/hooks/post-commit to automatically run sync_downstream.py --commit on every commit in this repository.

3. GitHub Actions CI/CD Sync

The .github/workflows/sync-downstream.yml workflow automatically propagates changes to the downstream GitHub repositories whene are pushed to main.

---

8. Running Tests & Hooks

1. Run Application QA & Security Test Suite

*Output: 10 tests passed ( both functional happy paths and security boundary rejection).*

2. Run Offline Hook Test Suites (Dependency-Free Mocks)

*Output: 76/76 mock tests passing (38 per test harness) across PASS, AD, ERROR, BLOCKED, FIXED, and PIPELINE outcomes.*

---

9. License

Licensed under the Apache License, 2.0.

项目信息

开发语言：Shell

Star 数：2

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Test-Driven Development agent framework with integrated threat modeling, defensive coding, security review hooks, and self-evolving skills for AI coding agents.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。