The `secaudit` Tool
Relevant source files
The following files were used as context for generating this wiki page:
The secaudit tool is a specialized component within the Zen MCP Server designed to perform systematic, multi-step security audits. It operates as a workflow-driven tool, guiding an AI agent through a comprehensive security investigation process that includes scope analysis, vulnerability assessment based on OWASP Top 10, and compliance evaluation. The tool is stateful, maintaining context across multiple steps to build a consolidated security posture assessment.
As part of a larger development workflow, secaudit is a key component of the secure-review skill, where it follows an initial code review and precedes a final pre-commit validation. This positions it as a deep-dive security analysis engine used for reviewing security-sensitive code, preparing for releases, or verifying compliance.
Sources: tools/secaudit.py, examples/skills/secure-review/SKILL.md, systemprompts/secaudit_prompt.py
Architecture and Workflow
The secaudit tool is built on the WorkflowTool architecture, which orchestrates a sequence of analysis steps. The workflow is designed to mimic a professional security audit, progressing from high-level scoping to detailed vulnerability analysis and final reporting.
Sources: tools/secaudit.py:11, tests/test_secaudit.py:155
Multi-Step Audit Process
The core of the tool is a pre-defined, six-step investigation process. At each step, the tool provides specific guidance to the AI agent on the required actions.
This diagram illustrates the standard six-step security audit workflow guided by the secaudit tool.
Expert Analysis
A key feature is the "expert analysis" phase. The tool triggers this phase when sufficient findings, relevant files, or identified issues have been accumulated throughout the workflow. When triggered, it consolidates all collected information and presents it to a powerful model for a final, in-depth security analysis. This can be skipped if confidence is "certain" or if use_assistant_model is set to False.
Sources: tools/secaudit.py:192-207, simulator_tests/test_secaudit_validation.py:440-471
Input Schema (SecauditRequest)
All interactions with the secaudit tool are governed by the SecauditRequest Pydantic model. This model defines the data structure for each step of the audit workflow, ensuring that all necessary context is passed between the user, the agent, and the AI model.
Sources: tools/secaudit.py:16-65, tests/test_secaudit.py:20-77
Class Diagram
The following diagram shows the structure of the SecauditRequest data model.
Sources: tools/secaudit.py:16-65
Request Parameters
The table below details the fields in the SecauditRequest model.
| Field | Type | Description | Default |
|---|---|---|---|
step | str | A description of the current security audit step being performed. | (Required) |
step_number | int | The current step number in the workflow. | (Required) |
total_steps | int | The total number of steps planned for the audit. | (Required) |
next_step_required | bool | Indicates if another step is required after this one. | (Required) |
findings | str | A summary of findings from the current investigation step. | (Required) |
files_checked | List[str] | A list of file paths that have been checked. | [] |
relevant_files | List[str] | A list of file paths identified as relevant to the audit. | [] |
relevant_context | List[str] | Specific functions, classes, or code blocks of interest. | [] |
issues_found | List[Dict] | A list of dictionaries, each representing a specific security issue found. | [] |
confidence | str | The agent's confidence level in its findings (low, medium, high, certain). | low |
security_scope | str | The context of the security audit (e.g., "Web application"). | "" |
threat_level | str | The assessed threat level (low, medium, high, critical). | medium |
compliance_requirements | List[str] | A list of compliance frameworks to consider (e.g., "PCI DSS", "SOC2"). | [] |
audit_focus | str | The primary focus of the audit (comprehensive, owasp, compliance, etc.). | comprehensive |
severity_filter | str | Filters issues by severity (all, medium, high, critical). | all |
Sources: tools/secaudit.py:16-65, tests/test_secaudit.py:40-52
Output Structure
The secaudit tool instructs the AI model to return a structured JSON object containing the complete analysis. This ensures that the output is predictable and can be easily parsed by downstream systems.
The core structure of the JSON response is defined in the system prompt and includes detailed sections for findings, risk assessment, and remediation.
This diagram shows the high-level keys in the expected JSON output.
security_findings Object
Each element in the security_findings array is a detailed object describing a single vulnerability.
| Field | Type | Description |
|---|---|---|
category | str | The OWASP category or security domain (e.g., "A03_Injection"). |
severity | str | The severity level: "Critical", "High", "Medium", or "Low". |
vulnerability | str | The specific name of the vulnerability (e.g., "SQL Injection"). |
description | str | A technical description of the security issue. |
impact | str | The potential business and technical impact of the vulnerability. |
remediation | str | Specific steps to fix the vulnerability. |
file_references | List[str] | A list of file paths and line numbers where the issue was found. |
Sources: systemprompts/secaudit_prompt.py:68-84
Systematic Investigation Methodology
The tool's system prompt enforces a rigorous investigation methodology, with a strong emphasis on the OWASP Top 10 (2021). The AI agent is instructed to systematically evaluate the codebase against each category.
| OWASP Category | Description |
|---|---|
A01_broken_access_control | Failures in enforcing restrictions on what authenticated users are allowed to do. |
A02_cryptographic_failures | Failures related to cryptography, which often lead to exposure of sensitive data. |
A03_injection | Flaws that allow untrusted data to be sent to an interpreter as part of a command or query. |
A04_insecure_design | Flaws representing missing or ineffective security controls due to a flawed design. |
A05_security_misconfiguration | Issues such as insecure default configurations, incomplete configurations, or verbose errors. |
A06_vulnerable_components | Using components with known vulnerabilities. |
A07_identification_authentication_failures | Failures in user identity, authentication, and session management. |
A08_software_data_integrity_failures | Failures related to software updates, critical data, and CI/CD pipelines without integrity verification. |
A09_security_logging_monitoring_failures | Insufficient logging, monitoring, or incident response. |
A10_server_side_request_forgery | Flaws that allow an attacker to induce the server-side application to make requests to an unintended location. |
Sources: systemprompts/secaudit_prompt.py:86-127, 219-304
Usage in Workflows
The secaudit tool is designed to be part of a larger chain of tools, as demonstrated by the secure-review skill. This skill defines a workflow for a comprehensive security review.
The diagram below shows the flow of the secure-review skill.
Testing and Validation
The secaudit tool is validated through both unit tests and end-to-end simulator tests. The simulator test test_secaudit_validation.py creates temporary files with known vulnerabilities and runs a full, multi-step audit against them to ensure the tool behaves as expected.
The following snippet from the validation test demonstrates a multi-step audit session, where findings from the first step are used to inform the second.
# simulator_tests/test_secaudit_validation.py:183-223
# Step 1: Initial security audit request
response, continuation_id = self.call_mcp_tool_direct(
"secaudit",
{
"step": f"Begin security audit of authentication system in {self.auth_file}",
"step_number": 1,
"total_steps": 6,
"next_step_required": True,
# ... other params
},
)
# ...
# Step 2: Continue with findings
response2, _ = self.call_mcp_tool_direct(
"secaudit",
{
"step": "Examined authentication module and found critical security vulnerabilities",
"step_number": 2,
"total_steps": 6,
"next_step_required": True,
"findings": (
"Found multiple OWASP Top 10 vulnerabilities: "
"1. SQL injection in login method (line 88)..."
),
"issues_found": [
{"severity": "critical", "description": "SQL injection vulnerability in login method"},
# ... other issues
],
"continuation_id": continuation_id,
# ... other params
},
)
Sources: simulator_tests/test_secaudit_validation.py, tests/test_secaudit.py
Conclusion
The secaudit tool provides a robust and structured framework for conducting automated, AI-driven security audits. By combining a systematic, multi-step workflow with the analytical power of large language models, it enables deep and comprehensive security analysis that is both repeatable and auditable. Its integration into larger skills like secure-review makes it a powerful asset for embedding security directly into the development lifecycle.
Sources: tools/secaudit.py, systemprompts/secaudit_prompt.py