# mrfrazer25/ai-osint-security-analyzer architecture

> Architecture diagram of the GitHub repository mrfrazer25/ai-osint-security-analyzer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrfrazer25/ai-osint-security-analyzer
- Repository: https://github.com/mrfrazer25/ai-osint-security-analyzer

## Overview

##### Project type and purpose
- This is a full-stack Python application with a Streamlit front-end (app.py) and a backend AI orchestration module (ai.py). Its goal is to perform autonomous OSINT (Open-Source Intelligence) security investigations by calling multiple external intelligence APIs and then presenting a synthesized risk assessment in a web UI.

##### File structure
- Top-level scripts:
- app.py – Streamlit entry point (presentation layer)
- ai.py – Core AI agent logic and orchestration (business logic layer)
- setup.py / pyproject.toml / requirements.txt – Installation, environment setup, and packaging
- Configuration:
- .streamlit/config.toml – Streamlit runtime settings
- .env (generated via setup.py) – API key storage (session-only environment variables)
- No persistent storage or database directories—analysis is entirely in memory.

##### Extract architectural hints from the README
- The AI agent “automatically selects tools, executes them in sequence, correlates findings, and synthesizes reports.”
- Integrations include Cohere Command A, Shodan, VirusTotal, AbuseIPDB, CVE-Search, CISA KEV, NVD.
- UI complexity levels (Quick Scan, Deep Dive) invoke the same core toolset.

##### Main components and their interactions
a. Components:
- User / Browser (Streamlit UI)
- Streamlit Server (app.py)
- AI Agent Orchestrator (ai.py)
- External OSINT Services (Cohere, Shodan, VirusTotal, etc.)
- Configuration Store (.env / Streamlit secrets)
b. Relationships & data flow:
– User submits target → Streamlit UI
– UI invokes AI Agent → loads config (API keys)
– AI Agent calls multiple external APIs in a defined sequence
– Responses returned to AI Agent → correlation & synthesis
– Final report fed back to UI → rendered in browser
c. Architectural patterns:
– Layered design (Presentation → Business Logic → Integration)
– Pipeline/orchestration pattern for multi-step tool execution
– In-memory processing (no database)
d. Key technologies:
– Python 3.8+
– Streamlit (front-end)
– Cohere Command A (AI model)
– Shodan, VirusTotal, AbuseIPDB, CVE-Search, CISA KEV, NVD (external APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Setup
    subgraph "Configuration & Setup"
        ConfigSecrets[".env (API Keys)"]:::config
        StreamlitConfig["Streamlit Runtime Configuration\n(.streamlit/config.toml)"]:::config
        Setup["Environment & Secrets Setup\n(setup.py)"]:::config
        PyProject["Packaging Definition\n(pyproject.toml)"]:::config
        Requirements["Dependencies\n(requirements.txt)"]:::config
        Docs["Documentation & Metadata\n(README.md, LICENSE)"]:::config
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        Browser["User / Browser"]:::frontend
        Streamlit["Streamlit UI\n(app.py)"]:::frontend
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        AI["AI Orchestrator\n(ai.py)"]:::logic
        subgraph "Orchestration Pipeline"
            TA["Target Analyzer"]:::logic
            TS["Tool Selector"]:::logic
            EP["Executor Pipeline"]:::logic
            CS["Correlator / Synthesizer"]:::logic
        end
    end

    %% External Services
    subgraph "External OSINT Services"
        Cohere["Cohere Command A"]:::external
        Shodan["Shodan"]:::external
        VirusTotal["VirusTotal"]:::external
        AbuseIPDB["AbuseIPDB"]:::external
        CVESearch["CVE-Search"]:::external
        CISAKEV["CISA KEV"]:::external
        NVD["NVD"]:::external
    end

    %% Data Flow
    Browser -->|"enters target"| Streamlit
    Streamlit -->|"invokes scan"| AI
    ConfigSecrets -->|provides API keys| AI
    StreamlitConfig -->|streamlit settings| Streamlit
    Setup -->|generates .env| ConfigSecrets
    PyProject -->|defines packaging| Setup
    Requirements -->|defines deps| Setup
    Docs -->|project info| Setup

    AI -->|analyzes target| TA
    TA --> TS
    TS --> EP
    EP --> Cohere
    EP --> Shodan
    EP --> VirusTotal
    EP --> AbuseIPDB
    EP --> CVESearch
    EP --> CISAKEV
    EP --> NVD
    Cohere --> EP
    Shodan --> EP
    VirusTotal --> EP
    AbuseIPDB --> EP
    CVESearch --> EP
    CISAKEV --> EP
    NVD --> EP
    EP --> CS
    CS --> AI
    AI -->|"returns report"| Streamlit
    Streamlit -->|"renders report"| Browser

    note["No persistent storage\n(in-memory processing)"]:::note

    %% Click Events
    click Streamlit "https://github.com/mrfrazer25/ai-osint-security-analyzer/blob/main/app.py"
    click StreamlitConfig "https://github.com/mrfrazer25/ai-osint-security-analyzer/blob/main/.streamlit/config.toml"
    click AI "https://github.com/mrfrazer25/ai-osint-security-analyzer/blob/main/ai.py"
    click Setup "https://github.com/mrfrazer25/ai-osint-security-analyzer/blob/main/setup.py"
    click PyProject "https://github.com/mrfrazer25/ai-osint-security-analyzer/blob/main/pyproject.toml"
    click Requirements "https://github.com/mrfrazer25/ai-osint-security-analyzer/blob/main/requirements.txt"
    click Docs "https://github.com/mrfrazer25/ai-osint-security-analyzer/blob/main/README.md"
    click Docs "https://github.com/mrfrazer25/ai-osint-security-analyzer/tree/main/LICENSE"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#1E70BF,color:#0B3D91;
    classDef logic fill:#DFF6E4,stroke:#297B3D,color:#1B3D1B;
    classDef external fill:#FFE1B0,stroke:#BF5E01,color:#803D00;
    classDef config fill:#E0E0E0,stroke:#888888,color:#444444;
    classDef note fill:#F5F5F5,stroke:#AAAAAA,color:#555555,stroke-dasharray: 5 5;
```
