# anshumanbh/vulnvibes architecture

> Architecture diagram of the GitHub repository anshumanbh/vulnvibes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anshumanbh/vulnvibes
- Repository: https://github.com/anshumanbh/vulnvibes

## Overview

VulnVibes accepts a GitHub pull request through its CLI or Python API, then runs threat modeling followed—when warranted—by skill-guided vulnerability investigation. The workflow uses GitHub tools to examine diffs and code, parses agent responses into structured findings, and can produce JSON and Markdown reports. The README documents the major workflow and capabilities; sampled source confirms key orchestration and tool relationships. Some integrations and report paths are documented rather than fully visible in the excerpts.

Main entry points: [`vulnvibes/orchestrator/__init__.py`](https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/orchestrator/__init__.py) (PR Orchestrator), [`vulnvibes/orchestrator/stages.py`](https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/orchestrator/stages.py) (Stage Execution), [`vulnvibes/cli.py`](https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/cli.py) (CLI), [`vulnvibes/agents/definitions.py`](https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/agents/definitions.py) (Agent Definitions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry"]
  node_cli["CLI<br/>[cli.py]"]
  node_input["PR Input<br/>[models.py]"]
end

subgraph group_workflow["Triage Workflow"]
  node_orchestrator["PR Orchestrator<br/>[__init__.py]"]
  node_stages["Stage Execution<br/>[stages.py]"]
  node_schemas["Output Schemas<br/>[schemas.py]"]
  node_logging["Logging<br/>[logging.py]"]
end

subgraph group_analysis["Analysis Resources"]
  node_agents["Agent Definitions<br/>[definitions.py]"]
  node_skill_registry["Skill Registry<br/>[skill_registry.py]"]
  node_skills["Investigation Skills"]
  node_config["Model Configuration<br/>[config.py]"]
end

subgraph group_integrations["External Access"]
  node_github_tools["GitHub Tools<br/>[github_tools.py]"]
  node_github_client["GitHub Client<br/>[github_client.py]"]
end

subgraph group_results["Results"]
  node_parsers["Response Parsers<br/>[parsers.py]"]
  node_reports["Report Generation<br/>[reports.py]"]
end

node_user(("Engineer"))
node_github(("GitHub"))
node_claude(("Claude Agent SDK"))

node_user -->|"runs analysis"| node_cli
node_user -->|"provides PR"| node_input
node_cli -->|"invokes"| node_orchestrator
node_cli -->|"creates"| node_input
node_orchestrator -->|"runs stages"| node_stages
node_orchestrator -->|"creates agents"| node_agents
node_orchestrator -->|"creates tools"| node_github_tools
node_orchestrator -->|"saves reports"| node_reports
node_stages -->|"queries agents"| node_agents
node_stages -->|"loads skill coverage"| node_skill_registry
node_agents -->|"builds skill prompts"| node_skill_registry
node_skill_registry -->|"discovers skills"| node_skills
node_stages -->|"uses schemas"| node_schemas
node_stages -->|"parses responses"| node_parsers
node_stages -->|"requests GitHub data"| node_github_tools
node_github_tools -->|"calls client"| node_github_client
node_github_client -->|"fetches PR and code"| node_github
node_github_tools -->|"registers MCP tools"| node_claude
node_stages -->|"queries agents"| node_claude
node_agents -->|"selects models"| node_config
node_cli -->|"configures logging"| node_logging
node_orchestrator -->|"analyzes PR input"| node_input
node_parsers -.->|"supplies findings"| node_reports
node_orchestrator -->|"returns results"| node_user

click node_cli "https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/cli.py"
click node_input "https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/models.py"
click node_orchestrator "https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/orchestrator/__init__.py"
click node_stages "https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/orchestrator/stages.py"
click node_agents "https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/agents/definitions.py"
click node_skill_registry "https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/skill_registry.py"
click node_skills "https://github.com/anshumanbh/vulnvibes/tree/main/vulnvibes/skills"
click node_schemas "https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/orchestrator/schemas.py"
click node_parsers "https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/orchestrator/parsers.py"
click node_reports "https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/orchestrator/reports.py"
click node_github_tools "https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/providers/github_tools.py"
click node_github_client "https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/providers/github_client.py"
click node_config "https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/config.py"
click node_logging "https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/utils/logging.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_input toneBlue
class node_orchestrator,node_stages,node_schemas,node_logging toneAmber
class node_agents,node_skill_registry,node_skills,node_config toneMint
class node_github_tools,node_github_client toneRose
class node_parsers,node_reports,node_user,node_github,node_claude toneIndigo
```

## Components

### User Entry

- [CLI](https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/cli.py): `vulnvibes/cli.py`
- [PR Input](https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/models.py): `vulnvibes/models.py`

### Triage Workflow

- [PR Orchestrator](https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/orchestrator/__init__.py): `vulnvibes/orchestrator/__init__.py`
- [Stage Execution](https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/orchestrator/stages.py): `vulnvibes/orchestrator/stages.py`
- [Output Schemas](https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/orchestrator/schemas.py): `vulnvibes/orchestrator/schemas.py`
- [Logging](https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/utils/logging.py): `vulnvibes/utils/logging.py`

### Analysis Resources

- [Agent Definitions](https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/agents/definitions.py): `vulnvibes/agents/definitions.py`
- [Skill Registry](https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/skill_registry.py): `vulnvibes/skill_registry.py`
- [Investigation Skills](https://github.com/anshumanbh/vulnvibes/tree/main/vulnvibes/skills): `vulnvibes/skills`
- [Model Configuration](https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/config.py): `vulnvibes/config.py`

### External Access

- [GitHub Tools](https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/providers/github_tools.py): `vulnvibes/providers/github_tools.py`
- [GitHub Client](https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/providers/github_client.py): `vulnvibes/providers/github_client.py`

### Results

- [Response Parsers](https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/orchestrator/parsers.py): `vulnvibes/orchestrator/parsers.py`
- [Report Generation](https://github.com/anshumanbh/vulnvibes/blob/main/vulnvibes/orchestrator/reports.py): `vulnvibes/orchestrator/reports.py`

### Other components

- **Engineer**
- **GitHub**
- **Claude Agent SDK**

## Connections

- Engineer → CLI: runs analysis (evidence: `README.md`)
- Engineer → PR Input: provides PR (evidence: `README.md`)
- CLI → PR Orchestrator: invokes (evidence: `vulnvibes/cli.py`)
- CLI → PR Input: creates (evidence: `vulnvibes/cli.py`)
- PR Orchestrator → Stage Execution: runs stages (evidence: `vulnvibes/orchestrator/__init__.py`)
- PR Orchestrator → Agent Definitions: creates agents (evidence: `vulnvibes/orchestrator/__init__.py`)
- PR Orchestrator → GitHub Tools: creates tools (evidence: `vulnvibes/orchestrator/__init__.py`)
- PR Orchestrator → Report Generation: saves reports (evidence: `vulnvibes/orchestrator/__init__.py`)
- Stage Execution → Agent Definitions: queries agents (evidence: `vulnvibes/orchestrator/stages.py`)
- Stage Execution → Skill Registry: loads skill coverage (evidence: `vulnvibes/orchestrator/stages.py`)
- Agent Definitions → Skill Registry: builds skill prompts (evidence: `vulnvibes/agents/definitions.py`)
- Skill Registry → Investigation Skills: discovers skills (evidence: `vulnvibes/skill_registry.py`)
- Stage Execution → Output Schemas: uses schemas (evidence: `vulnvibes/orchestrator/stages.py`)
- Stage Execution → Response Parsers: parses responses (evidence: `vulnvibes/orchestrator/stages.py`)
- Stage Execution → GitHub Tools: requests GitHub data (evidence: `README.md`)
- GitHub Tools → GitHub Client: calls client (evidence: `vulnvibes/providers/github_tools.py`)
- GitHub Client → GitHub: fetches PR and code (evidence: `README.md`)
- GitHub Tools → Claude Agent SDK: registers MCP tools (evidence: `vulnvibes/providers/github_tools.py`)
- Stage Execution → Claude Agent SDK: queries agents (evidence: `vulnvibes/orchestrator/stages.py`)
- Agent Definitions → Model Configuration: selects models (evidence: `vulnvibes/agents/definitions.py`)
- CLI → Logging: configures logging (evidence: `vulnvibes/cli.py`)
- PR Orchestrator → PR Input: analyzes PR input (evidence: `README.md`)
- Response Parsers → Report Generation: supplies findings
- PR Orchestrator → Engineer: returns results (evidence: `README.md`)
