# j0rdan-m/ansible-vulnerability-scanner architecture

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

- Interactive diagram: https://gitdiagram.com/j0rdan-m/ansible-vulnerability-scanner
- Repository: https://github.com/j0rdan-m/ansible-vulnerability-scanner

## Overview

This GitHub Action scans configured Ansible YAML playbooks, extracts package names and versions from selected package-manager tasks, queries a chosen vulnerability provider, and writes a Markdown or SARIF report. The main script owns provider selection, playbook iteration, cached lookup, and report dispatch; provider modules normalize findings into a shared vulnerability model. README documents the Action inputs, three provider choices, and report formats. Provider and generator behavior is shown in sampled source; the README also documents GitHub Code Scanning as a SARIF consumer.

Main entry points: [`ansible-vulnerability-scan.py`](https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/ansible-vulnerability-scan.py) (Scanner entry point), [`vuln_providers/nist_provider.py`](https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/vuln_providers/nist_provider.py) (NIST provider), [`vuln_providers/osv_provider.py`](https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/vuln_providers/osv_provider.py) (OSV provider), [`vuln_providers/oss_index_provider.py`](https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/vuln_providers/oss_index_provider.py) (OSS Index provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan["Playbook scanning"]
  node_scanner_entry["Scanner entry point"]
  node_playbook_scan["Playbook scanning"]
end

subgraph group_providers["Vulnerability providers"]
  node_lookup_cache["Lookup cache"]
  node_provider_factory["Provider selection"]
  node_nist_provider["NIST provider<br/>[nist_provider.py]"]
  node_osv_provider["OSV provider<br/>[osv_provider.py]"]
  node_oss_provider["OSS Index provider"]
end

subgraph group_reports["Findings and reports"]
  node_vulnerability["Vulnerability model"]
  node_markdown_generator["Markdown generator"]
  node_sarif_generator["SARIF generator<br/>[sarif_generator.py]"]
end

node_github_user(("Workflow author"))
node_nvd_api{{"NVD API"}}
node_osv_api{{"OSV API"}}
node_oss_api{{"OSS Index API"}}
node_code_scanning(("GitHub Code Scanning"))

node_github_user -->|"configures and runs"| node_scanner_entry
node_scanner_entry -->|"selects provider"| node_provider_factory
node_scanner_entry -->|"scans playbooks"| node_playbook_scan
node_playbook_scan -->|"checks packages"| node_lookup_cache
node_lookup_cache -->|"queries when selected"| node_nist_provider
node_lookup_cache -->|"queries when selected"| node_osv_provider
node_lookup_cache -->|"queries when selected"| node_oss_provider
node_nist_provider -->|"requests CVEs"| node_nvd_api
node_osv_provider -->|"queries advisories"| node_osv_api
node_oss_provider -->|"queries components"| node_oss_api
node_nist_provider -->|"creates finding"| node_vulnerability
node_osv_provider -->|"creates finding"| node_vulnerability
node_oss_provider -->|"creates finding"| node_vulnerability
node_scanner_entry -->|"writes Markdown"| node_markdown_generator
node_scanner_entry -->|"writes SARIF"| node_sarif_generator
node_github_user -.->|"consumes SARIF"| node_code_scanning

click node_scanner_entry "https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/ansible-vulnerability-scan.py"
click node_playbook_scan "https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/ansible-vulnerability-scan.py"
click node_lookup_cache "https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/ansible-vulnerability-scan.py"
click node_provider_factory "https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/ansible-vulnerability-scan.py"
click node_nist_provider "https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/vuln_providers/nist_provider.py"
click node_osv_provider "https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/vuln_providers/osv_provider.py"
click node_oss_provider "https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/vuln_providers/oss_index_provider.py"
click node_vulnerability "https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/vulnerability_model.py"
click node_markdown_generator "https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/generators/markdown_generator.py"
click node_sarif_generator "https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/generators/sarif_generator.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_scanner_entry,node_playbook_scan toneBlue
class node_lookup_cache,node_provider_factory,node_nist_provider,node_osv_provider,node_oss_provider toneAmber
class node_vulnerability,node_markdown_generator,node_sarif_generator,node_nvd_api,node_osv_api,node_oss_api toneMint
class node_github_user,node_code_scanning toneIndigo
```

## Components

### Playbook scanning

- [Scanner entry point](https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/ansible-vulnerability-scan.py): `ansible-vulnerability-scan.py`
- [Playbook scanning](https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/ansible-vulnerability-scan.py): `ansible-vulnerability-scan.py`

### Vulnerability providers

- [Lookup cache](https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/ansible-vulnerability-scan.py): `ansible-vulnerability-scan.py`
- [Provider selection](https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/ansible-vulnerability-scan.py): `ansible-vulnerability-scan.py`
- [NIST provider](https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/vuln_providers/nist_provider.py): `vuln_providers/nist_provider.py`
- [OSV provider](https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/vuln_providers/osv_provider.py): `vuln_providers/osv_provider.py`
- [OSS Index provider](https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/vuln_providers/oss_index_provider.py): `vuln_providers/oss_index_provider.py`

### Findings and reports

- [Vulnerability model](https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/vulnerability_model.py): `vulnerability_model.py`
- [Markdown generator](https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/generators/markdown_generator.py): `generators/markdown_generator.py`
- [SARIF generator](https://github.com/j0rdan-m/ansible-vulnerability-scanner/blob/main/generators/sarif_generator.py): `generators/sarif_generator.py`

### Other components

- **Workflow author**
- **NVD API**
- **OSV API**
- **OSS Index API**
- **GitHub Code Scanning**

## Connections

- Workflow author → Scanner entry point: configures and runs (evidence: `README.md`)
- Scanner entry point → Provider selection: selects provider (evidence: `ansible-vulnerability-scan.py`)
- Scanner entry point → Playbook scanning: scans playbooks (evidence: `ansible-vulnerability-scan.py`)
- Playbook scanning → Lookup cache: checks packages (evidence: `ansible-vulnerability-scan.py`)
- Lookup cache → NIST provider: queries when selected (evidence: `ansible-vulnerability-scan.py`)
- Lookup cache → OSV provider: queries when selected (evidence: `ansible-vulnerability-scan.py`)
- Lookup cache → OSS Index provider: queries when selected (evidence: `ansible-vulnerability-scan.py`)
- NIST provider → NVD API: requests CVEs (evidence: `vuln_providers/nist_provider.py`)
- OSV provider → OSV API: queries advisories (evidence: `vuln_providers/osv_provider.py`)
- OSS Index provider → OSS Index API: queries components (evidence: `vuln_providers/oss_index_provider.py`)
- NIST provider → Vulnerability model: creates finding (evidence: `vuln_providers/nist_provider.py`)
- OSV provider → Vulnerability model: creates finding (evidence: `vuln_providers/osv_provider.py`)
- OSS Index provider → Vulnerability model: creates finding (evidence: `vuln_providers/oss_index_provider.py`)
- Scanner entry point → Markdown generator: writes Markdown (evidence: `ansible-vulnerability-scan.py`)
- Scanner entry point → SARIF generator: writes SARIF (evidence: `ansible-vulnerability-scan.py`)
- Workflow author → GitHub Code Scanning: consumes SARIF (evidence: `README.md`)
