Security Researcher Agent

Overview

Layers 3–4 on the Mental Model. The Security Researcher is the only agent: OpenAI Agents SDK inside FastAPI, Semgrep over MCP stdio, structured SecurityReport out.

Behavior

• Single Runner.run. One upload triggers one agent run; there is no multi-agent handoff.
• Semgrep once. semgrep_scan must use config: auto and run only once; then the model reviews results and looks for missed issues.
• Structured output. output_type=SecurityReport — summary plus issues with title, description, snippet, fix, CVSS, severity.
• Ephemeral path. Temp .py exists only for the scan window; API unlinks it after the run.
• Prompt Chaining. Scan → review → combine → typed report. See Building effective agents.

Scan flow

One Python file after upload. Diagram key: ✦ AI agent · second line = Anthropic workflow · purple = actor · white = service.

---
config:
  theme: default
  themeVariables:
    background: "#ffffff"
    fontSize: "14px"
---
flowchart TB
    person[Developer]
    api["POST /api/analyze"]
    tmp[Temp .py]
    researcher["✦ Security Researcher
Prompt Chaining"]
    mcp[Semgrep MCP]
    openai[OpenAI API]
    report[SecurityReport JSON]

    person -->|upload| api --> tmp
    api -->|Runner.run| researcher
    researcher -->|semgrep_scan once| mcp
    mcp -->|read path| tmp
    researcher -->|Agents SDK| openai
    openai -->|typed report| researcher
    researcher --> api --> report --> person

    classDef agent fill:#e8f0ee,stroke:#0f3d36,stroke-width:2px,color:#0d0d0d
    classDef service fill:#fafaf8,stroke:#c8c8c2,stroke-width:1px,color:#0d0d0d
    classDef actor fill:#f3eef8,stroke:#6b4f9a,stroke-width:2px,color:#0d0d0d
    class researcher agent
    class api,tmp,mcp,openai,report service
    class person actor

Prompt: SECURITY_RESEARCHER_INSTRUCTIONS in context.py. Model: gpt-4.1-mini. Route: POST /api/analyze.