security-advisor 0.1.0__py3-none-any.whl

pkg/sarif_report.py

@@ -0,0 +1,180 @@
+from datetime import datetime, timezone
+import json
+
+# ---------------------------------------------------------------------------
+# SARIF 2.1.0 builder
+# ---------------------------------------------------------------------------
+
+def _severity_to_sarif_level(severity: str) -> str:
+    """Map a tool-specific severity string to a SARIF notification level."""
+    mapping = {
+        "critical": "error",
+        "high":     "error",
+        "medium":   "warning",
+        "low":      "note",
+        "info":     "note",
+    }
+    return mapping.get(severity.lower(), "warning")
+
+
+def _parse_sast_results(sast_json: dict) -> tuple[list, list]:
+    """Convert Semgrep JSON output to SARIF rules + results."""
+    rules, results = [], []
+    seen_rule_ids: set[str] = set()
+
+    for finding in sast_json.get("results", []):
+        rule_id   = finding.get("check_id", "unknown-rule")
+        message   = finding.get("extra", {}).get("message", "No message.")
+        severity  = finding.get("extra", {}).get("severity", "warning")
+        file_path = finding.get("path", "")
+        start     = finding.get("start", {})
+        end       = finding.get("end", {})
+
+        if rule_id not in seen_rule_ids:
+            seen_rule_ids.add(rule_id)
+            rules.append({
+                "id": rule_id,
+                "name": rule_id,
+                "shortDescription": {"text": message[:200]},
+                "helpUri": finding.get("extra", {}).get("metadata", {}).get("references", [None])[0],
+                "properties": {"tags": ["SAST", "semgrep"]},
+            })
+
+        results.append({
+            "ruleId": rule_id,
+            "level": _severity_to_sarif_level(severity),
+            "message": {"text": message},
+            "locations": [{
+                "physicalLocation": {
+                    "artifactLocation": {"uri": file_path, "uriBaseId": "%SRCROOT%"},
+                    "region": {
+                        "startLine":   start.get("line", 1),
+                        "startColumn": start.get("col", 1),
+                        "endLine":     end.get("line", start.get("line", 1)),
+                        "endColumn":   end.get("col", 1),
+                    },
+                }
+            }],
+        })
+
+    return rules, results
+
+
+def _parse_trivy_results(trivy_json: dict, scan_type: str) -> tuple[list, list]:
+    """Convert Trivy JSON output (vuln or config) to SARIF rules + results."""
+    rules, results = [], []
+    seen_rule_ids: set[str] = set()
+    tags = ["SCA", "trivy"] if scan_type == "sca" else ["IaC", "trivy"]
+
+    for target_block in trivy_json.get("Results", []):
+        target   = target_block.get("Target", "")
+        findings = target_block.get("Vulnerabilities") or target_block.get("Misconfigurations") or []
+
+        for finding in findings:
+            # Vulnerabilities use VulnerabilityID; Misconfigurations use ID
+            rule_id   = finding.get("VulnerabilityID") or finding.get("ID", "unknown")
+            title     = finding.get("Title") or finding.get("Description", rule_id)
+            desc      = finding.get("Description", title)
+            severity  = finding.get("Severity", "UNKNOWN")
+            pkg_name  = finding.get("PkgName", "")
+            fixed_ver = finding.get("FixedVersion", "")
+            refs      = finding.get("References") or finding.get("References", [])
+
+            if rule_id not in seen_rule_ids:
+                seen_rule_ids.add(rule_id)
+                help_uri = refs[0] if refs else None
+                rules.append({
+                    "id": rule_id,
+                    "name": rule_id,
+                    "shortDescription": {"text": title[:200]},
+                    "fullDescription":  {"text": desc[:1000]},
+                    **({"helpUri": help_uri} if help_uri else {}),
+                    "properties": {"tags": tags},
+                })
+
+            message_parts = [f"{title} in `{pkg_name or target}`."]
+            if fixed_ver:
+                message_parts.append(f"Fixed in version: {fixed_ver}.")
+
+            results.append({
+                "ruleId": rule_id,
+                "level": _severity_to_sarif_level(severity),
+                "message": {"text": " ".join(message_parts)},
+                "locations": [{
+                    "physicalLocation": {
+                        "artifactLocation": {"uri": target, "uriBaseId": "%SRCROOT%"},
+                    }
+                }],
+            })
+
+    return rules, results
+
+
+def build_sarif_report(sast_raw: str, sca_raw: str, iac_raw: str) -> dict:
+    """
+    Aggregate SAST, SCA, and IaC scan outputs into a single SARIF 2.1.0 document.
+    Returns the SARIF document as a Python dict.
+    """
+    sast_json = json.loads(sast_raw) if sast_raw.strip() else {}
+    sca_json  = json.loads(sca_raw)  if sca_raw.strip()  else {}
+    iac_json  = json.loads(iac_raw)  if iac_raw.strip()  else {}
+
+    sast_rules, sast_results = _parse_sast_results(sast_json)
+    sca_rules,  sca_results  = _parse_trivy_results(sca_json,  "sca")
+    iac_rules,  iac_results  = _parse_trivy_results(iac_json,  "iac")
+
+    sarif: dict = {
+        "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [
+            # ── SAST run (Semgrep) ──────────────────────────────────────────
+            {
+                "tool": {
+                    "driver": {
+                        "name":           "Semgrep",
+                        "informationUri": "https://semgrep.dev",
+                        "version":        "latest",
+                        "rules":          sast_rules,
+                    }
+                },
+                "results":   sast_results,
+                "invocations": [{
+                    "executionSuccessful": True,
+                    "endTimeUtc": datetime.now(timezone.utc).isoformat(),
+                }],
+            },
+            # ── SCA run (Trivy – vulnerabilities) ──────────────────────────
+            {
+                "tool": {
+                    "driver": {
+                        "name":           "Trivy",
+                        "informationUri": "https://trivy.dev",
+                        "version":        "latest",
+                        "rules":          sca_rules,
+                    }
+                },
+                "results":   sca_results,
+                "invocations": [{
+                    "executionSuccessful": True,
+                    "endTimeUtc": datetime.now(timezone.utc).isoformat(),
+                }],
+            },
+            # ── IaC run (Trivy – misconfigurations) ────────────────────────
+            {
+                "tool": {
+                    "driver": {
+                        "name":           "Trivy",
+                        "informationUri": "https://trivy.dev",
+                        "version":        "latest",
+                        "rules":          iac_rules,
+                    }
+                },
+                "results":   iac_results,
+                "invocations": [{
+                    "executionSuccessful": True,
+                    "endTimeUtc": datetime.now(timezone.utc).isoformat(),
+                }],
+            },
+        ],
+    }
+    return sarif

security_advisor-0.1.0.dist-info/METADATA

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: security-advisor
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=3.2.4
+Requires-Dist: mcp>=1.27.1
+Dynamic: license-file
+
+# 🛡️ Security Advisor
+
+An **MCP (Model Context Protocol) server** that orchestrates comprehensive security scans — SAST, SCA, and IaC — across any project and produces a unified **SARIF 2.1.0** report consumable by GitHub Advanced Security, VS Code, and other industry-standard tooling.
+
+---
+
+## Overview
+
+Security Advisor exposes four MCP tools that an AI assistant (e.g., Claude, Gemini) can invoke to analyse a codebase:
+
+| Tool | Description |
+|---|---|
+| `security_sast_skill` | Static Application Security Testing via **Semgrep** |
+| `security_sca_skill` | Software Composition Analysis via **Trivy** (dependency vulnerabilities) |
+| `security_iac_scan_skill` | Infrastructure-as-Code misconfiguration scan via **Trivy** (Terraform, K8s, Docker) |
+| `security_advisor_skill` | **Master skill** — runs all three scans in parallel and exports a unified SARIF report |
+
+### How It Works
+
+```
+AI Assistant
+    │
+    └─► security_advisor_skill(project_path)
+             │
+             ├─► security_sast_skill      →  Semgrep JSON
+             ├─► security_sca_skill       →  Trivy vuln JSON
+             └─► security_iac_scan_skill  →  Trivy config JSON
+                          │
+                          ▼
+                  build_sarif_report()      ← pkg/sarif_report.py
+                          │
+                          ▼
+          <project_path>/Security-Advisor-Report.sarif
+```
+
+---
+
+## Prerequisites
+
+Ensure the following are installed and available on your `PATH` before running Security Advisor.
+
+### System Tools
+
+| Tool | Version | Install |
+|---|---|---|
+| **Python** | ≥ 3.14 | [python.org](https://www.python.org/downloads/) |
+| **uv** | latest | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
+| **Semgrep** | latest | `pip install semgrep` or `brew install semgrep` |
+| **Trivy** | latest | `brew install trivy` or see [trivy.dev](https://trivy.dev/latest/getting-started/installation/) |
+
+### Verify Prerequisites
+
+```bash
+python3 --version   # Should be 3.14+
+uv --version
+semgrep --version
+trivy --version
+```
+
+---
+
+## Project Structure
+
+```
+security-advisor/
+├── main.py               # MCP server entry point — exposes all scan tools
+├── pkg/
+│   ├── __init__.py
+│   └── sarif_report.py   # SARIF 2.1.0 builder (parses Semgrep + Trivy JSON)
+├── pyproject.toml        # Project metadata and dependencies
+├── uv.lock               # Locked dependency manifest
+├── .python-version       # Pinned Python version (3.14)
+└── README.md
+```
+
+---
+
+## Installation
+
+### 1. Clone the repository
+
+```bash
+git clone <repository-url>
+cd security-advisor
+```
+
+### 2. Create and activate a virtual environment with `uv`
+
+```bash
+uv venv
+source .venv/bin/activate   # macOS / Linux
+# .venv\Scripts\activate    # Windows
+```
+
+### 3. Install dependencies
+
+```bash
+uv pip install -e .
+```
+
+This installs:
+- [`fastmcp`](https://github.com/jlowin/fastmcp) ≥ 3.2.4 — high-level MCP server framework
+- [`mcp`](https://github.com/modelcontextprotocol/python-sdk) ≥ 1.27.1 — Model Context Protocol Python SDK
+
+---
+
+## Development
+
+### Running the MCP Server Locally
+
+```bash
+uv run main.py
+```
+
+Or via the standard Python entrypoint:
+
+```bash
+python main.py
+```
+
+The server starts and listens for MCP tool calls over **stdio** (default FastMCP transport).
+
+### Running with `fastmcp` dev mode
+
+```bash
+fastmcp dev main.py
+```
+
+This launches an interactive MCP inspector at `http://localhost:6274` so you can test tools manually.
+
+---
+
+## MCP Client Configuration
+
+To connect Security Advisor to an AI assistant, add it to your MCP client config.
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "security-advisor": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/absolute/path/to/security-advisor",
+        "run",
+        "main.py"
+      ]
+    }
+  }
+}
+```
+
+### Gemini / Antigravity (`.gemini/settings.json`)
+
+```json
+{
+  "mcpServers": {
+    "security-advisor": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/absolute/path/to/security-advisor",
+        "run",
+        "main.py"
+      ]
+    }
+  }
+}
+```
+
+> **Tip:** Replace `/absolute/path/to/security-advisor` with the actual path on your machine.
+
+---
+
+## Usage
+
+### Via an AI Assistant
+
+Once the MCP server is connected, instruct your assistant:
+
+```
+Run a full security analysis on /path/to/my-project
+```
+
+The assistant will invoke `security_advisor_skill`, which:
+1. Runs Semgrep SAST, Trivy SCA, and Trivy IaC scans **in parallel**
+2. Aggregates all findings into a SARIF 2.1.0 document
+3. Writes the report to `<project_path>/Security-Advisor-Report.sarif`
+4. Returns a human-readable summary
+
+### Individual Tools
+
+You can also invoke individual scan tools:
+
+```
+Run a SAST scan on /path/to/my-project
+Run an SCA scan on /path/to/my-project
+Run an IaC scan on /path/to/my-project
+```
+
+---
+
+## SARIF Report
+
+The exported **`Security-Advisor-Report.sarif`** is a valid [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html) document containing three `runs`:
+
+| Run | Tool | Findings |
+|---|---|---|
+| `runs[0]` | Semgrep | SAST code-level issues |
+| `runs[1]` | Trivy | SCA dependency vulnerabilities |
+| `runs[2]` | Trivy | IaC misconfigurations |
+
+### Severity Mapping
+
+| Tool Severity | SARIF Level |
+|---|---|
+| `CRITICAL`, `HIGH` | `error` |
+| `MEDIUM` | `warning` |
+| `LOW`, `INFO` | `note` |
+
+### Viewing the Report
+
+- **GitHub**: Upload to [Code Scanning](https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github) via `gh` CLI or Actions
+- **VS Code**: Install the [SARIF Viewer extension](https://marketplace.visualstudio.com/items?itemName=MS-SarifVSCode.sarif-viewer)
+- **Any SARIF-compatible tool**: The file adheres to the official OASIS schema
+
+```bash
+# Upload to GitHub Code Scanning
+gh api \
+  --method POST \
+  /repos/{owner}/{repo}/code-scanning/sarifs \
+  --field commit_sha=$(git rev-parse HEAD) \
+  --field ref=$(git symbolic-ref HEAD) \
+  --field sarif=@Security-Advisor-Report.sarif
+```
+
+---
+
+## Dependencies
+
+| Package | Version | Purpose |
+|---|---|---|
+| `fastmcp` | ≥ 3.2.4 | MCP server framework |
+| `mcp` | ≥ 1.27.1 | Model Context Protocol Python SDK |
+
+External CLI tools (not Python packages):
+
+| Tool | Purpose |
+|---|---|
+| `semgrep` | SAST scanning |
+| `trivy` | SCA + IaC scanning |
+
+---
+
+## Contributing
+
+1. Fork the repository and create a feature branch
+2. Make your changes and ensure the server starts cleanly (`uv run main.py`)
+3. Test manually using `fastmcp dev main.py`
+4. Open a pull request with a clear description of the changes
+
+---
+
+## License
+
+This project is licensed under the **MIT License**.

security_advisor-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+pkg/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pkg/sarif_report.py,sha256=jeg4aonATV_alU4ACvi4QWBdmlrYsWv_2h2Q41nXHtI,7444
+security_advisor-0.1.0.dist-info/licenses/LICENSE,sha256=BqSdBAFLSGpS17yvP58nw1oG--7fKcwjPWxy-gyPl-4,1071
+security_advisor-0.1.0.dist-info/METADATA,sha256=XZ-H3kLAnpZP9u4to-aEIYQqODlErihm3F0ndafk9xE,7071
+security_advisor-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+security_advisor-0.1.0.dist-info/top_level.txt,sha256=8jjfKuFvlaNGG7JiuNtS31gIuwOm8thUcUQoNbsxxls,4
+security_advisor-0.1.0.dist-info/RECORD,,

security_advisor-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

security_advisor-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya Byreddy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

security_advisor-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pkg