{
  "markdown": "<div align=\"center\">\n\n<img src=\"banner.png\" alt=\"Security SAST Guard banner\" width=\"100%\">\n\n# 🛡️ SECURITY SAST GUARD PLUGIN\n**Zero-Trust Enterprise SAST & Real-time Command Firewall Engine**\n*Engineered for Google Antigravity 2.0 & Gemini CLI Ecosystems*\n\n[![CI Quality Gate](https://github.com/nguyenduydan/security-sast-guard-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/nguyenduydan/security-sast-guard-plugin/actions/workflows/ci.yml)\n[![CodeQL Security](https://github.com/nguyenduydan/security-sast-guard-plugin/actions/workflows/codeql.yml/badge.svg)](https://github.com/nguyenduydan/security-sast-guard-plugin/actions/workflows/codeql.yml)\n[![Release Status](https://github.com/nguyenduydan/security-sast-guard-plugin/actions/workflows/release.yml/badge.svg)](https://github.com/nguyenduydan/security-sast-guard-plugin/actions/workflows/release.yml)\n[![Latest Release](https://img.shields.io/github/v/release/nguyenduydan/security-sast-guard-plugin?color=10b981)](https://github.com/nguyenduydan/security-sast-guard-plugin/releases)\n[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)\n[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n[![Type Checked: MyPy](https://img.shields.io/badge/type%20checked-mypy%20strict-blue.svg)](https://mypy-lang.org/)\n[![MCP Server](https://img.shields.io/badge/MCP-Stdio%20Server%20(12%20Tools)-violet.svg)](#-stdio-mcp-server-integration)\n[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n[⚡ Quick Start](#-quick-start) • [🗺️ Roadmap](docs/ROADMAP.md) • [📚 Project Wiki](docs/wiki/Home.md) • [🧠 Architecture](docs/ARCHITECTURE.md) • [🛡️ Security Model](docs/SECURITY_MODEL.md) • [🔌 MCP Server](#-stdio-mcp-server-integration) • [🎮 Slash Commands & CLI](#-slash-commands--cli-reference) • [🛡️ Security Vectors](#-security-vectors--rule-coverage) • [🔄 CI/CD & Release](#-cicd-workflow--quality-gates)\n\n</div>\n\n---\n\n## ⚡ Quick Start\n\n### Windows (PowerShell)\n```powershell\n# Install Security SAST Guard Plugin\nInvoke-WebRequest -Uri \"https://raw.githubusercontent.com/nguyenduydan/security-sast-guard-plugin/main/install.ps1\" -OutFile \"install.ps1\"\n.\\install.ps1\n\n# Update (Preserves local .sast/profile.json configuration)\ncd $HOME\\.gemini\\config\\plugins\\security-sast-guard; .\\update.ps1\n\n# Uninstall\ncd $HOME\\.gemini\\config\\plugins\\security-sast-guard; .\\remove.ps1\n```\n\n### Linux & macOS (POSIX Shell)\n```bash\n# Install Security SAST Guard Plugin\ncurl -fsSL https://raw.githubusercontent.com/nguyenduydan/security-sast-guard-plugin/main/install.sh -o install.sh\nchmod +x install.sh && ./install.sh\n\n# Update (Preserves local .sast/profile.json configuration)\ncd ~/.gemini/config/plugins/security-sast-guard && ./update.sh\n\n# Uninstall\ncd ~/.gemini/config/plugins/security-sast-guard && ./remove.sh\n```\n\n---\n\n## 🧠 Architecture & 13 Modular Subsystems\n\nSecurity SAST Guard introduces a symbiotic AI-agent security architecture combining a **10-Stage Command Interception Firewall** with an **Intelligence-Driven SAST Engine**.\n\n```mermaid\nflowchart TD\n    subgraph Input[\"Execution & AI Agents\"]\n        ShellCmd[\"Shell Command Execution\"]\n        AICodeEdit[\"AI Code Modification / Context\"]\n        MCPClient[\"Stdio MCP Client (Antigravity 2.0)\"]\n    end\n\n    subgraph Tier1[\"Tier 1: Security Core Firewall & Decision\"]\n        Deobf[\"FirewallNormalizer (10-Stage Deobfuscation)\"]\n        CapClass[\"FirewallCapabilityClassifier (7 Groups)\"]\n        IntentClass[\"FirewallIntentClassifier (Capability Set Reasoning)\"]\n        ChainAnal[\"FirewallChainAnalyzer (Multi-Command Threat Chains)\"]\n        DecisionEng[\"SecurityDecisionEngine (4-State Formal Machine)\"]\n        FPTracker[\"SemanticFingerprintTracker (SHA-256 Location-Agnostic)\"]\n        RuleInteg[\"RuleIntegrityValidator (SHA-256 & ReDoS Protection)\"]\n        AuditLog[\"AppendOnlyAuditLog (.sast/firewall_audit.jsonl)\"]\n    end\n\n    subgraph Tier2[\"Tier 2: SAST Intelligence Engine\"]\n        EvidEngine[\"EvidenceEngine & Program Slicer\"]\n        Harness[\"BoundedVerificationHarness (Resource Guard)\"]\n        AdaptiveKB[\"AdaptiveKnowledgeBase & Sanitizer Registry\"]\n        MetricsMapper[\"CWEOWASPMapper & SecurityMetricsEngine\"]\n        FrameworkSem[\"FrameworkSemanticsRegistry (ASP.NET WebForms / React / Generic)\"]\n        AuditSvc[\"AuditService (Unified v2 Pipeline)\"]\n    end\n\n    subgraph Tier3[\"Tier 3: Developer Experience & Exporters\"]\n        TUI[\"Pure ANSI TUIRenderer\"]\n        SARIF[\"Enhanced ISO SARIF 2.1.0 Exporter\"]\n        MCPServer[\"Stdio MCP Server (12 Security Tools)\"]\n    end\n\n    ShellCmd -->|\"Hook Intercept\"| Deobf\n    Deobf --> CapClass --> IntentClass --> ChainAnal --> DecisionEng\n    DecisionEng --> AuditLog\n    AICodeEdit --> AuditSvc\n    MCPClient <-->|\"JSON-RPC Stdio\"| MCPServer\n    MCPServer --> AuditSvc\n    AuditSvc --> FrameworkSem --> EvidEngine --> Harness --> AdaptiveKB --> MetricsMapper\n    AuditSvc --> FPTracker\n    AuditSvc --> TUI & SARIF\n```\n\n### Breakdown of the 13 Core Modules\n\n| Module Name | Tier | Core Responsibility & Architectural Role |\n| :--- | :---: | :--- |\n| **1. FirewallNormalizer** | Security Core | 10-stage command deobfuscation (Caret/Backtick, Base64, Hex/Unicode escape, Env vars, Interpolation, Char codes, Aliases, Subcommands, Decomposition). |\n| **2. FirewallCapabilityClassifier** | Security Core | Maps deobfuscated commands across 7 capability groups (`NETWORK`, `FILE_READ`, `FILE_WRITE`, `PROCESS_EXEC`, `PRIVILEGE_CHANGE`, `PERSISTENCE`, `DATA_TRANSFER`). |\n| **3. FirewallIntentClassifier** | Security Core | Reasons intent from capability sets (`EXFILTRATION`, `DESTRUCTIVE`, `PERSISTENCE`, `PRIVILEGE_ESCALATION`, `SUPPLY_CHAIN`, `LATERAL_MOVEMENT`). |\n| **4. FirewallChainAnalyzer** | Security Core | Detects hazardous multi-command execution chains (e.g. `Download+Execute`, execution policy bypass, unverified script invocation). |\n| **5. SecurityDecisionEngine** | Security Core | Formal 4-state decision machine (`TRUE_POSITIVE`, `FALSE_POSITIVE`, `CONFIRM_REQUIRED`, `NOT_ENOUGH_CONTEXT`) with weighted risk scoring & policy overrides. |\n| **6. SemanticFingerprintTracker** | Security Core | Generates line-agnostic SHA-256 finding signatures to maintain baseline state across refactorings; detects tamper (T7). |\n| **7. RuleIntegrityValidator** | Security Core | Verifies SHA-256 rule definitions integrity (T5) and detects Catastrophic Backtracking (ReDoS) patterns in rule regexes. |\n| **8. AppendOnlyAuditLog** | Security Core | Cryptographically chained, append-only JSONL log (`.sast/firewall_audit.jsonl`) verifying full execution auditability. |\n| **9. EvidenceEngine** | SAST Intelligence | Extracts `EvidenceGraph` nodes (`source`, `propagation`, `sanitizer`, `sink`) and computes minimal relevant Program Slices. |\n| **10. BoundedVerificationHarness** | SAST Intelligence | Enforces resource limits on AI verification loops (max 5 iterations, 10 tool calls, 30s timeout, 1MB output, 20 files, 128MB RAM). |\n| **11. AdaptiveKnowledgeBase** | SAST Intelligence | Sanitizer governance registry with mandatory Human/Policy approval gate and cryptographic provenance hashes. |\n| **12. CWEOWASPMapper & Metrics** | SAST Intelligence | Maps findings to CWE IDs and OWASP Top 10 categories; calculates Precision, Recall, F1 Score, FPR, FNR, and Critical Recall metrics. |\n| **13. FrameworkSemanticsRegistry**| SAST Intelligence | Multi-language framework strategy plugin framework supporting ASP.NET WebForms (`<asp:TextBox>`, `<%: %>`), React, and Generic fallbacks. |\n\n---\n\n## 🔌 Stdio MCP Server Integration\n\nAdd `sast-guard` to your project or global `mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"sast-guard\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"src.mcp.server\"],\n      \"cwd\": \"${workspaceFolder}\"\n    }\n  }\n}\n```\n\n### Complete Stdio MCP Tools Suite (12 Tools)\n\n| Stdio MCP Tool Name | Primary Purpose | Key Arguments & Input Schema | Output / Response Format |\n| :--- | :--- | :--- | :--- |\n| `sast_scan_file` | Audits single file with taint traces | `file_path` (string) | JSON findings array, taint traces & summary |\n| `sast_scan_diff` | Incremental Git diff security audit | None | Audit summary of modified lines & findings |\n| `sast_check_command` | Validates shell command safety | `command` (string) | Firewall verdict (`ALLOW`, `CONFIRM`, `DENY`), risk score |\n| `sast_get_status` | Returns profile & system status | None | Active level, mode, rule counts, deny/confirm lists |\n| `sast_set_mode` | Switches strictness mode | `mode` (`\"strict\"` \\| `\"draft\"`) | Confirmation status & mode applied |\n| `sast_set_level` | Adjusts inspection audit depth | `level` (`\"lite\"` \\| `\"full\"` \\| `\"ultra\"`) | Confirmation & active rule scope |\n| `sast_init` | Initializes local project config | None | Path to created `.sast/profile.json` |\n| `sast_sync_rules` | Synchronizes security rules | `rules_dir` (optional string) | Synced rule count & validation status |\n| `sast_get_help` | Fetches command & rule guidance | None | Slash commands list & vector coverage map |\n| `sast_get_dataflow_path` | Traces source-to-sink dataflows | `source_pattern`, `sink_pattern`, `repo_path` | Structured dataflow path nodes & line numbers |\n| `sast_get_taint_context` | Retrieves code context for taint line | `file_path`, `line_number`, `context_lines` | Code snippet block with line annotations |\n| `sast_generate_report` | Generates SARIF / Markdown report | `findings`, `target_path`, `ai_analysis` | Path to generated `.sarif` and `.md` reports |\n\n---\n\n## 🖥️ Pure ANSI TUI & SARIF 2.1.0 Exporter\n\n### Pure ANSI TUI Renderer\nBuilt with zero external dependencies (pure Python ANSI codes), providing crisp terminal rendering:\n- Dynamic Version Header resolved dynamically via `get_plugin_version()`.\n- Interactive Real-time Scan Progress bars with file counters.\n- Rich Boxed Finding Cards featuring code snippets, CWE/OWASP tags, and remediation guidance.\n- Distinctly styled Firewall Verdict boxes: **`DENY`** (Red), **`CONFIRM`** (Yellow), **`ALLOW`** (Green).\n\n### Enhanced SARIF 2.1.0 Report Exporter\nGenerates standard ISO SARIF 2.1.0 artifacts compatible with GitHub Code Scanning, SonarQube, and CI pipelines:\n- Full taxonomy tags for **CWE** (e.g. `CWE-79`, `CWE-89`) and **OWASP Top 10** (`A03:2021-Injection`).\n- Embedded SHA-256 semantic fingerprints for issue tracking across commits.\n- Precise `threadFlows` and `location` graphs mapping dataflow propagation from source to sink.\n\n---\n\n## 🎮 Slash Commands & CLI Reference\n\n### Slash Commands & CLI Commands Matrix\n\n| Slash Command | CLI Command | Description |\n| :--- | :--- | :--- |\n| 🛡️ `/sast-audit [type] [path]` | `sast scan [path]` | Runs security audit (`folder`, `file`, `diff`, `codebase`, `api`, `web`) with automatic AI root-cause triage when SDK is present. |\n| 📊 `/sast-status` | `sast status` | Displays active profile, audit level, mode, and loaded rule count. |\n| 🚀 `/sast-init` | `sast init` | Creates local `.sast/profile.json` security configuration. |\n| 🎛️ `/sast-mode [strict\\|draft]` | `sast mode [mode]` | `strict` enforces zero high/critical tolerance; `draft` logs only. |\n| 🎚️ `/sast-audit-level [lite\\|full\\|ultra]` | `sast level [level]` | Configures scanning depth (`lite`: fast regex, `full`: AST, `ultra`: Taint). |\n| 🛠️ `/sast-rules [sync\\|add]` | `sast rules` | Synchronizes rule directory or validates custom `.md` rule specs. |\n| 🧱 `/sast-firewall [command]` | `sast firewall [cmd]` | Checks command safety against 10-stage normalizer (`ALLOW`, `CONFIRM`, `DENY`). |\n| 🆘 `/sast-help` | `sast help` | Displays quick command reference and security vectors guide. |\n\n### Extended CLI Flags\n- `--no-ai`: Disables AI root-cause triage and forces pure static analysis mode.\n- `--json <file_path>` / `--format json`: Exports scan findings as machine-readable structured JSON.\n- `-v` / `--verbose`: Enables verbose debug trace output for deep inspection.\n\n\n---\n\n## 🤖 Google Antigravity SDK Integration (`google-antigravity`)\n\nSecurity SAST Guard embeds the **Google Antigravity Python SDK** as an optional extra (`[ai]`) to provide non-intrusive, zero-trust AI root-cause triage directly within your IDE:\n\n```bash\n# Install with optional AI Agent triage support\npip install -e \".[ai]\"\n```\n\n### 🌟 Key Agentic AI Highlights\n1. **Local Zero-Cost Execution:** Leverages active Google Antigravity IDE / CLI login quotas — **zero extra API keys or fees required**.\n2. **Deterministic SHA-256 Cache:** Previously analyzed code snippets are served instantly with **0 tokens consumed**.\n3. **Token Accounting Telemetry:** Reports exact `Input`, `Thinking`, `Output`, and `Total Tokens` consumed.\n4. **Zero-Trust Hardening:** Hardcoded `CapabilitiesConfig(disabled_tools=[\"run_command\", \"edit_file\", \"create_file\", \"start_subagent\"])` prevents prompt injection attacks from modifying your workspace.\n5. **Graceful Fallback:** If `google-antigravity` is not installed or running offline, the tool automatically falls back to 100% heuristic static analysis without crashing.\n\n\n---\n\n## 📁 Custom Exclusions & Blacklist Configuration\n\nSecurity SAST Guard automatically ignores built-in build caches, `.git`, dependencies (`node_modules`, `.venv`, `vendor`), and lock files.\n\nTo customize scan exclusions for your repository, use either of the following:\n\n### 1. Standalone `blacklist.json` (Recommended)\nPlace `blacklist.json` at your project root or in `.sast/blacklist.json`:\n```json\n[\n  \"tests/fixtures/*\",\n  \"legacy_module/\",\n  \"generated_*.py\",\n  \"*.min.js\",\n  \"mock_data.json\"\n]\n```\n\n### 2. Standard `.sastignore`\nCreate a `.sastignore` file at your repository root with glob patterns:\n```gitignore\n# Ignore test fixtures and temporary generated files\ntests/fixtures/*\nbuild_artifacts/\n*.tmp\n```\n\n## 🛡️ Security Vectors & Rule Coverage\n\nSecurity SAST Guard implements **95 core SAST vector rules** mapped across major enterprise standards:\n\n| Framework / Category | Rule Count | High-Impact Vector Examples |\n| :--- | :---: | :--- |\n| **OWASP Web Application Top 10** | 28 | Broken Access Control (A01), Cryptographic Failure (A02), Injection (A03), Deserialization RCE (A08) |\n| **Web Application Specific Rules** | 29 | DOM XSS, Inline Event Handlers, SQLi Variants, SSTI, Unsafe File Upload |\n| **OWASP API Security Top 10** | 27 | BOLA (API1), Broken Auth (API2), Mass Assignment (API3), SSRF (API7) |\n| **OWASP LLM 2025 Top 10** | 3 | Prompt Injection (LLM01), Sensitive Information Disclosure (LLM02), Excessive Agency (LLM06) |\n| **CI/CD & Container Security** | 4 | GitHub Actions Expression Injection, Unsafe Checkout, Docker Root Execution |\n| **CWE-SANS & NIST 800-53** | 4 | OS Command Injection (CWE-78), Path Traversal (CWE-22), Audit Events |\n\n### Inline Suppression Syntax\nTo suppress specific rule alerts on a target line, append `# sast-ignore [RULE_ID]`:\n```python\nquery = f\"SELECT * FROM users WHERE id = {user_id}\"  # sast-ignore [OWASP-A03-SQLI]\n```\n\n---\n\n## 🔄 CI/CD Workflow & Quality Gates\n\nSecurity SAST Guard enforces strict pre-commit and automated release workflows via GitHub Actions:\n\n- **CI Workflow (`.github/workflows/ci.yml`):** Runs on all Pull Requests and pushes to `main`.\n  1. **Ruff Format & Linting:** Enforces PEP 8 and formatting standards (`ruff check .` & `ruff format --check .`).\n  2. **Pylint Quality Gate:** Verifies core code quality (`pylint control_plane.py src/`).\n  3. **MyPy Type Checking:** Ensures strict static typing (`mypy --config-file=pyproject.toml control_plane.py src/`).\n  4. **Pytest Suite:** Runs 100% passing test coverage (`pytest`).\n- **Release Workflow (`.github/workflows/release.yml`):** Managed automatically by `release-please` v4. Automatically drafts PRs, bumps versions, updates `CHANGELOG.md`, and creates tagged GitHub Releases upon merge.\n\n---\n\n## 📚 Enterprise Project Wiki\n\nExplore the full enterprise-grade documentation suite in [`docs/wiki/`](docs/wiki/Home.md):\n\n| Wiki Module | Focus Area & Description | Direct Link |\n| :--- | :--- | :---: |\n| 🏠 **Home & Quick Start** | System overview, two-tier Zero-Trust defense model, 1-Click Installer for PowerShell & POSIX Bash | [`Home.md`](docs/wiki/Home.md) |\n| 🧠 **Architecture & Security Model** | 10-Stage Deobfuscation, Threat Chains, AST Engine, Taint Tracking, Shannon Entropy | [`Architecture-and-Security-Model.md`](docs/wiki/Architecture-and-Security-Model.md) |\n| 🎮 **CLI & Slash Commands** | Complete reference for 8 AI Agent Slash Commands, CLI syntax, Blacklist & Exclusions | [`CLI-and-Slash-Commands.md`](docs/wiki/CLI-and-Slash-Commands.md) |\n| 🔌 **MCP Server Integration** | 12 Stdio MCP Tools specifications, connection setup for Antigravity 2.0, Gemini CLI, Claude, Cursor | [`MCP-Server-Integration.md`](docs/wiki/MCP-Server-Integration.md) |\n| 🛡️ **Rule Engine & Taxonomy** | 95 Security Vectors, OWASP/CWE/NIST mappings, `# sast-ignore` inline syntax, Markdown sync | [`Rule-Engine-and-Taxonomy.md`](docs/wiki/Rule-Engine-and-Taxonomy.md) |\n| 🔄 **CI/CD & Quality Gates** | ISO SARIF 2.1.0 export for GitHub Security, 4 CI Quality Gates, Conventional Commits, Release Please v4 | [`CI-CD-and-Quality-Gates.md`](docs/wiki/CI-CD-and-Quality-Gates.md) |\n\n---\n\n## 🤝 Contributing & License\n\nDistributed under the [MIT License](LICENSE). See [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/RELEASE_GUIDE.md](docs/RELEASE_GUIDE.md) for contribution & release guidelines.\n",
  "bytes": 17707,
  "sha": "ab9ee8657ba63f5a102e6dc70c928d60851532e5893a1e9b743d3b9f15b394eb",
  "repo_slug": "nguyenduydan/security-sast-guard-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_nguyenduydan_security_sast_guard_plugin_d4aa4f7e/readme"
}