# scs-labrat/oh-my-osint architecture

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

- Interactive diagram: https://gitdiagram.com/scs-labrat/oh-my-osint
- Repository: https://github.com/scs-labrat/oh-my-osint

## Overview

##### Project type and purpose
- This is a single-page, full-stack Python application built on Streamlit. It provides an interactive OSINT (Open Source INTelligence) reconnaissance assistant that:
- Presents a web UI (Streamlit)
- Automates selection and execution of CLI tools
- Queries external OSINT APIs
- Leverages Google Gemini (LLM) for tool recommendations and report generation
- Generates and serves downloadable Markdown reports

##### File structure
- Top-level scripts:
- install-script.sh / oh-my-osint.sh – helper scripts to bootstrap and install dependencies and CLI tools
- oh-my-osint.py – main Python orchestration script (entry point for Streamlit UI and backend logic)
- Requirements and config:
- requirements.txt – Python dependencies (Streamlit, requests, Gemini client, various APIs)
- .gitignore – standard excludes
- README.md – contains usage instructions, feature list, and directory overview

##### Extract architectural insights from README
- Streamlit handles the frontend interface
- The app invokes a selection module (powered by Google Gemini) to decide which OSINT tools to run
- It calls multiple CLI tools (theHarvester, amass, etc.) and HTTP-based OSINT APIs (crt.sh, Shodan, AbuseIPDB, etc.)
- Results feed back into the LLM for summarization into a Markdown report
- The UI offers a download link for the generated report

##### Main components
a. Streamlit Frontend
– UI layer (forms for target input, buttons to install tools, execute recon, download report)
b. Orchestration Layer (Python logic in oh-my-osint.py)
– Gemini Tool-Selector (LLM API client)
– CLI-Tool Runner (wrapper to invoke theHarvester, amass, sublist3r, etc.)
– API Integrator (HTTP clients for crt.sh, ipinfo.io, Shodan, AbuseIPDB)
– Data Aggregator (collects all outputs)
– Gemini Report Generator (passes aggregated data to LLM)
– Report Formatter (constructs Markdown)
c. External Services
– Google Gemini API
– OSINT APIs (crt.sh, ipinfo.io, Shodan, AbuseIPDB, viewdns.info)
d. Local/Downloadable Output
– Markdown report stored in memory or temp storage, served via Streamlit download button

##### Relationships and data flow
- User → Streamlit UI → Orchestrator
- Orchestrator → Gemini Tool-Selector → returns list of tools
- Orchestrator → CLI-Tool Runner → executes tools, captures STDOUT
- Orchestrator → API Integrator → fetches additional data
- Aggregator collates CLI + API outputs → Gemini Report Generator
- Gemini returns summary → Report Formatter → Markdown
- Streamlit UI ← serves Markdown + Download control

##### Architectural patterns and principles
- Clear separation of concerns:
- UI vs Orchestration vs External integrations
- Modular design:
- Each tool/integration as a separate wrapper module
- LLM calls encapsulated in a “LLM client” component
- Pluggability/extensibility:
- New CLI tools or APIs can be added via new modules without touching UI code

##### Essential elements
- Component names and boundaries
- External dependencies clearly separated
- Brief annotation of technology (e.g., “Streamlit (Python)”, “Gemini LLM API”)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend UI
    UI["Streamlit UI\n(Streamlit)"]:::ui

    %% Backend Orchestrator
    subgraph "Orchestrator"
        TS["Gemini Tool-Selector"]:::orchestrator
        CTR["CLI-Tool Runner"]:::orchestrator
        APII["API Integrator"]:::orchestrator
        DA["Data Aggregator"]:::orchestrator
        GR["Gemini Report Generator"]:::orchestrator
        RF["Report Formatter"]:::orchestrator
    end

    %% External Services
    subgraph "External Services"
        Gem["Google Gemini API"]:::external
        subgraph "OSINT HTTP APIs"
            crt["crt.sh"]:::external
            shodan["Shodan API"]:::external
            abuse["AbuseIPDB API"]:::external
            ipinfo["ipinfo.io API"]:::external
            viewdns["viewdns.info API"]:::external
        end
        subgraph "CLI Tools"
            CLI1["theHarvester"]:::external
            CLI2["amass"]:::external
            CLI3["sublist3r"]:::external
        end
    end

    %% Output Storage
    MD["Markdown Report"]:::storage

    %% Project Assets
    subgraph "Project Assets"
        Inst1["install-script.sh"]:::asset
        Inst2["oh-my-osint.sh"]:::asset
        Req["requirements.txt"]:::asset
        Docs["README.md"]:::asset
        Git[".gitignore"]:::asset
    end

    %% Data Flow
    UI -->|"start reconnaissance"| TS
    TS -->|"selected tools"| CTR
    CTR -->|"invoke theHarvester"| CLI1
    CTR -->|"invoke amass"| CLI2
    CTR -->|"invoke sublist3r"| CLI3
    CTR -->|"send raw output"| DA
    APII -->|"GET /crt.sh"| crt
    APII -->|"GET /shodan"| shodan
    APII -->|"GET /abuseipdb"| abuse
    APII -->|"GET /ipinfo"| ipinfo
    APII -->|"GET /viewdns"| viewdns
    APII -->|"send API data"| DA
    DA -->|"aggregate data"| GR
    GR -->|"Chat Completion API"| Gem
    Gem -->|"LLM response"| GR
    GR -->|"summary data"| RF
    RF -->|"format Markdown"| MD
    UI -->|"serve report"| MD

    %% Click Events
    click UI "https://github.com/scs-labrat/oh-my-osint/blob/main/oh-my-osint.py"
    click TS "https://github.com/scs-labrat/oh-my-osint/blob/main/oh-my-osint.py"
    click CTR "https://github.com/scs-labrat/oh-my-osint/blob/main/oh-my-osint.py"
    click APII "https://github.com/scs-labrat/oh-my-osint/blob/main/oh-my-osint.py"
    click DA "https://github.com/scs-labrat/oh-my-osint/blob/main/oh-my-osint.py"
    click GR "https://github.com/scs-labrat/oh-my-osint/blob/main/oh-my-osint.py"
    click RF "https://github.com/scs-labrat/oh-my-osint/blob/main/oh-my-osint.py"
    click Inst1 "https://github.com/scs-labrat/oh-my-osint/blob/main/install-script.sh"
    click Inst2 "https://github.com/scs-labrat/oh-my-osint/blob/main/oh-my-osint.sh"
    click Req "https://github.com/scs-labrat/oh-my-osint/blob/main/requirements.txt"
    click Docs "https://github.com/scs-labrat/oh-my-osint/blob/main/README.md"
    click Git "https://github.com/scs-labrat/oh-my-osint/blob/main/.gitignore"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef orchestrator fill:#d4edda,stroke:#28a745,color:#000;
    classDef external fill:#fff3cd,stroke:#ffcc00,color:#000;
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#000,shape:cylinder;
    classDef asset fill:#f8f9fa,stroke:#adb5bd,color:#000;
```
