Skip to content

DeepTeam is a framework to red team LLMs and AI agents.

feat: add reporting (markdown, comments, sarif)

tanayvaswaniae151ef68e4a
diff --git a/deepteam/code_scanner/__init__.py b/deepteam/code_scanner/__init__.py
index c5a61055..2bfd0fcb 100644
--- a/deepteam/code_scanner/__init__.py
+++ b/deepteam/code_scanner/__init__.py
@@ -17,6 +17,19 @@ from .constants import (
from .template import CodeScanTemplate
from .code_scanner import CodeScanner
from .collect import collect_files, collect_changed_files
+from .config import (
+ CONFIG_FILENAMES,
+ CodeScanConfig,
+ find_config_file,
+ load_config,
+)
+from .report import (
+ SEVERITY_ORDER,
+ filter_by_severity,
+ to_json,
+ to_markdown,
+ to_sarif,
+)
__all__ = [
"CodeChunk",
@@ -33,4 +46,13 @@ __all__ = [
"CodeScanner",
"collect_files",
"collect_changed_files",
+ "CONFIG_FILENAMES",
+ "CodeScanConfig",
+ "find_config_file",
+ "load_config",
+ "SEVERITY_ORDER",
+ "filter_by_severity",
+ "to_json",
+ "to_markdown",
+ "to_sarif",
]
diff --git a/deepteam/code_scanner/code_scanner.py b/deepteam/code_scanner/code_scanner.py
index 3f4ecfa2..9cae998e 100644
--- a/deepteam/code_scanner/code_scanner.py
+++ b/deepteam/code_scanner/code_scanner.py
@@ -26,14 +26,14 @@ class CodeScanner:
model: DeepEvalBaseLLM,
template=CodeScanTemplate,
vulnerabilities: Optional[List[VulnerabilityRef]] = None,
- guidance: Optional[str] = None,
+ instruction: Optional[str] = None,
limit: int = CODE_CONTEXT_LIMIT,
max_concurrent: int = 10,
):
self.model, self.using_native_model = initialize_model(model)
self.template = template
self.vulnerabilities = vulnerabilities
- self.guidance = guidance
+ self.instruction = instruction
self.limit = limit
self.max_concurrent = max_concurrent
@@ -67,7 +67,7 @@ class CodeScanner:
return self.template.generate_code_batch_evaluation(
batch_data=batch_string,
vulnerabilities=self.vulnerabilities,
- guidance=self.guidance,
+ instruction=self.instruction,
)
def scan(self, chunks: List[CodeChunk]) -> List[CodeFinding]:
diff --git a/deepteam/code_scanner/config.py b/deepteam/code_scanner/config.py
new file mode 100644
index 00000000..f92c5ff5
--- /dev/null
+++ b/deepteam/code_scanner/config.py
@@ -0,0 +1,63 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+import yaml
+
+from .schema import Severity
+
+CONFIG_FILENAMES = (".deepteam-code-scan.yaml",)
+
+
+@dataclass
+class CodeScanConfig:
+ """
+ Settings for a code scan, loaded from a repo-root YAML file.
+
+ The instruction field is passed straight through to the scanner's
+ `instruction` parameter when the CLI constructs it.
+ """
+
+ min_severity: Severity = "low"
+ instruction: Optional[str] = None
+ include: Optional[List[str]] = None
+ exclude: Optional[List[str]] = None
+ vulnerabilities: Optional[List[str]] = None
+ model: Optional[str] = None
+ diffs_only: bool = False
+
+
+def find_config_file(directory: str = ".") -> Optional[str]:
+ """
+ Return the first recognized config file in `directory`, or None.
+ """
+ for name in CONFIG_FILENAMES:
+ candidate = Path(directory) / name
+ if candidate.is_file():
+ return str(candidate)
+ return None
+
+
+def load_config(
+ path: Optional[str] = None, directory: str = "."
+) -> CodeScanConfig:
+ """
+ Load scan config from an explicit `path`, or auto-discover one of
+ CONFIG_FILENAMES in `directory`. Returns defaults if none is found.
+ """
+ config_path = path or find_config_file(directory)
+ if not config_path or not Path(config_path).is_file():
+ return CodeScanConfig()
+
+ with open(config_path) as f:
+ raw = yaml.safe_load(f) or {}
+
+ return CodeScanConfig(
+ min_severity=raw.get("min_severity", "low"),
+ instruction=raw.get("instruction"),
+ include=raw.get("include"),
+ exclude=raw.get("exclude"),
+ vulnerabilities=raw.get("vulnerabilities"),
+ model=raw.get("model"),
+ diffs_only=bool(raw.get("diffs_only", False)),
+ )
diff --git a/deepteam/code_scanner/report.py b/deepteam/code_scanner/report.py
new file mode 100644
index 00000000..230ffeed
--- /dev/null
+++ b/deepteam/code_scanner/report.py
@@ -0,0 +1,138 @@
+import json
+from typing import Dict, List
+
+from .schema import CodeFinding
+
+SEVERITY_ORDER: Dict[str, int] = {
+ "low": 0,
+ "medium": 1,
+ "high": 2,
+ "critical": 3,
+}
+
+_SEVERITY_EMOJI = {
+ "critical": "\U0001f534",
+ "high": "\U0001f7e0",
+ "medium": "\U0001f7e1",
+ "low": "⚪",
+}
+
+_SARIF_LEVEL = {
+ "critical": "error",
+ "high": "error",
+ "medium": "warning",
+ "low": "note",
+}
+
+
+def filter_by_severity(
+ findings: List[CodeFinding], min_severity: str = "low"
+) -> List[CodeFinding]:
+ """Keep only findings at or above `min_severity`."""
+ threshold = SEVERITY_ORDER.get(min_severity, 0)
+ return [
+ f for f in findings if SEVERITY_ORDER.get(f.severity, 0) >= threshold
+ ]
+
+
+def to_json(findings: List[CodeFinding]) -> str:
+ return json.dumps(
+ [f.model_dump(exclude_none=True) for f in findings], indent=2
+ )
+
+
+def to_markdown(findings: List[CodeFinding]) -> str:
+ """Render findings as a PR-comment-friendly Markdown summary."""
+ if not findings:
+ return "## \U0001f6e1️ deepteam code scan\n\nNo vulnerabilities found."
+
+ counts = {s: 0 for s in SEVERITY_ORDER}
+ for f in findings:
+ counts[f.severity] = counts.get(f.severity, 0) + 1
+
+ summary = " · ".join(
+ f"{_SEVERITY_EMOJI[s]} {counts[s]} {s}"
+ for s in ("critical", "high", "medium", "low")
+ )
+ lines = [
+ "## \U0001f6e1️ deepteam code scan",
+ "",
+ f"**{len(findings)} finding(s)** — {summary}",
+ ]
+
+ by_file: Dict[str, List[CodeFinding]] = {}
+ for f in findings:
+ by_file.setdefault(f.filePath, []).append(f)
+
+ for path in sorted(by_file):
+ lines.append(f"\n### `{path}`")
+ ordered = sorted(
+ by_file[path],
+ key=lambda x: (-SEVERITY_ORDER.get(x.severity, 0), x.lineStart),
+ )
+ for f in ordered:
+ loc = f"L{f.lineStart}"
+ if f.lineEnd and f.lineEnd != f.lineStart:
+ loc += f"-{f.lineEnd}"
+ lines.append(
+ f"- {_SEVERITY_EMOJI[f.severity]} **{f.severity}** · "
+ f"`{f.vulnerability} / {f.vulnerabilityType}` — {loc}"
+ )
+ lines.append(f" {f.reason}")
+ if f.recommendation:
+ lines.append(f" _Fix:_ {f.recommendation}")
+
+ return "\n".join(lines)
+
+
+def to_sarif(findings: List[CodeFinding]) -> str:
+ """Render findings as SARIF 2.1.0 for GitHub's code-scanning UI."""
+ rules: Dict[str, dict] = {}
+ results: List[dict] = []
+
+ for f in findings:
+ rule_id = f"{f.vulnerability}/{f.vulnerabilityType}"
+ if rule_id not in rules:
+ rules[rule_id] = {
+ "id": rule_id,
+ "name": f.vulnerability,
+ "shortDescription": {
+ "text": f"{f.vulnerability}: {f.vulnerabilityType}"
+ },
+ }
+ region = {"startLine": f.lineStart}
+ if f.lineEnd:
+ region["endLine"] = f.lineEnd
+ results.append(
+ {
+ "ruleId": rule_id,
+ "level": _SARIF_LEVEL.get(f.severity, "warning"),
+ "message": {"text": f.reason},
+ "locations": [
+ {
+ "physicalLocation": {
+ "artifactLocation": {"uri": f.filePath},
+ "region": region,
+ }
+ }
+ ],
+ }
+ )
+
+ sarif = {
+ "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+ "version": "2.1.0",
+ "runs": [
+ {
+ "tool": {
+ "driver": {
+ "name": "deepteam",
+ "informationUri": "https://github.com/confident-ai/deepteam",
+ "rules": list(rules.values()),
+ }
+ },
+ "results": results,
+ }
+ ],
+ }
+ return json.dumps(sarif, indent=2)
diff --git a/deepteam/code_scanner/template.py b/deepteam/code_scanner/template.py
index a70af6b7..e10ba22a 100644
--- a/deepteam/code_scanner/template.py
+++ b/deepteam/code_scanner/template.py
@@ -35,23 +35,23 @@ class CodeScanTemplate:
def generate_code_batch_evaluation(
batch_data: str,
vulnerabilities: Optional[List[VulnerabilityRef]] = None,
- guidance: Optional[str] = None,
+ instruction: Optional[str] = None,
) -> str:
"""Build the evaluation prompt for one batch of code chunks.
Args:
batch_data: JSON array of code chunks. Each has `file_path`, `content`, optional `language`, and `start_line` (the absolute line number `content`'s first line maps to).
vulnerabilities: Vulnerability classes or name strings to scan for. Defaults to `DEFAULT_CODE_SCAN_VULNERABILITIES`. Pass a subset to scope.
- guidance: Optional free-text project guidance (e.g. "treat any PII exposure as high severity").
+ instruction: Optional free-text project instruction (e.g. "treat any PII exposure as high severity").
"""
vulnerabilities = vulnerabilities or DEFAULT_CODE_SCAN_VULNERABILITIES
catalog = CodeScanTemplate._render_catalog(vulnerabilities)
- guidance_block = ""
- if guidance and guidance.strip():
- guidance_block = (
- "\n ADDITIONAL PROJECT GUIDANCE (apply on top of the "
- f"above):\n {guidance.strip()}\n"
+ instruction_block = ""
+ if instruction and instruction.strip():
+ instruction_block = (
+ "\n ADDITIONAL PROJECT INSTRUCTION (apply on top of the "
+ f"above):\n {instruction.strip()}\n"
)
return f"""
@@ -88,7 +88,7 @@ class CodeScanTemplate:
4. `vulnerabilityType` MUST be one of the exact types listed for the
chosen category above.
5. Give a precise `reason`, an actionable `recommendation`, and the
- offending `codeSnippet`.{guidance_block}
+ offending `codeSnippet`.{instruction_block}
**
EXAMPLE JSON OUTPUT
diff --git a/examples/.deepteam-code-scan.yaml b/examples/.deepteam-code-scan.yaml
new file mode 100644
index 00000000..1fcecafe
--- /dev/null
+++ b/examples/.deepteam-code-scan.yaml
@@ -0,0 +1,8 @@
+min_severity: medium
+
+instruction: |
+ This is a customer-support agent. Treat hardcoded API keys and any
+ eval/exec on LLM output as critical.
+
+exclude:
+ - "tests/**"