# zenfish/satan architecture

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

- Interactive diagram: https://gitdiagram.com/zenfish/satan
- Repository: https://github.com/zenfish/satan

## Overview

##### Project Type and Purpose
- SATAN is a full-stack network vulnerability scanner with:
- A web front-end (CGI scripts in Perl under html/)
- An application-logic layer (Perl scripts and policy engine under perl/ and perllib/)
- A set of compiled probe binaries (C code under src/ → built into bin/)
- A file-based configuration & rules engine (config/ and rules/)

##### Main Components
A. Web Server / HTTP Interface
- e.g., Apache or NCSA HTTPd hosting html/*.pl CGIs
B. CGI Controllers (Perl)
- html/admin/*.pl, html/data/*.pl, html/running/*.pl, html/reporting/*.pl
- Entry points for user actions: configuration, execution, reporting
C. Application Logic Layer (Perl & Policy Engine)
- perl/*.pl scripts (policy-engine.pl, facts.pl, infer_facts.pl, etc.)
- perllib/ helper modules (getopts.pl, ctime.pl, etc.)
D. Configuration & Rules Store
- config/satan.cf, config/services, config/version.pl,
- rules/{facts,trust,services,…} defining vulnerability logic
E. Probe Binaries
- bin/*.satan wrappers invoking compiled C tools
- src/ subdirs (boot/, fping/, nfs-chk/, port_scan/, rpcgen/, yp-chk/)
F. Data Store
- Flat files or DB files under config/ or local working dir (satan.db?)
- “facts” produced by probes and policy engine
G. Reporting / HTML Renderer
- html/reporting/*.pl generating HTML pages from the data store

##### Relationships & Data Flow
1. User → HTTP Request → Web Server
2. Web Server → CGI Controller
3. CGI Controller ↔ Application Logic
- Loads config/satan.cf & rules
- Calls policy-engine to decide which probes to run
4. Application Logic → Spawns Probe Binaries (bin/)
5. Probe Binaries → Scan network targets → Produce raw “facts”
6. Application Logic ← Parses “facts” → Stores in Data Store
7. Reporting Controller → Reads Data Store → Renders HTML → User

##### Architectural Patterns & Principles
- MVC-like separation:
- View = HTML templates & generated pages
- Controller = html/*.pl scripts
- Model = policy engine + facts + rules + data store
- Modular plugin style:
- New probes added via src/ → compiled & dropped into bin/
- Rules in rules/ directory are pluggable
- File-based configuration for easy extension

##### Technology Stack Highlights
- Web server: CGI-capable (Perl)
- Perl 5 for business logic, controllers, and modules
- C for high-performance network probes
- Flat files for config, rules, and data persistence
- Makefile-driven build for C components (src/)
- Shell scripts (bin/*.satan) gluing Perl controllers to binaries

- Notes on key file locations (e.g., rules/ directory, config/satan.cf)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Users
    Admin["Administrator / Browser"]:::external
    TargetNet["Target Network"]:::external

    %% Web Server Layer
    subgraph "Web Server / HTTP Interface" 
        direction TB
        WebServer["HTTP Server (Apache/NCSA)"]:::ui
    end

    %% CGI Controllers
    subgraph "CGI Controllers" 
        direction TB
        CFAction["satan_cf_action.pl"]:::perl
        CFForm["satan_cf_form.pl"]:::perl
        DataForm["satan_data_form.pl"]:::perl
        MergeAction["satan_merge_action.pl"]:::perl
        OpenAction["satan_open_action.pl"]:::perl
        RunAction["satan_run_action.pl"]:::perl
        RunForm["satan_run_form.pl"]:::perl
        MainCGI["satan.pl"]:::perl
        DocCGI["satan_documentation.pl"]:::perl
    end

    %% Reporting Renderer
    subgraph "Reporting / HTML Renderer" 
        direction TB
        Reporting["html/reporting/*.pl"]:::ui
    end

    %% Application Logic Layer
    subgraph "Application Logic Layer" 
        direction TB
        PolicyEngine["policy-engine.pl"]:::perl
        Facts["facts.pl"]:::perl
        InferFacts["infer_facts.pl"]:::perl
        DropFact["drop_fact.pl"]:::perl
        RunSatan["run-satan.pl"]:::perl
        DataScript["satan-data.pl"]:::perl
    end

    %% Helper Modules
    subgraph "Perl Libraries (perllib/)" 
        direction TB
        Getopts["getopts.pl"]:::perl
        Ctime["ctime.pl"]:::perl
    end

    %% Config & Rules
    subgraph "Configuration Store" 
        direction TB
        ConfigCF["satan.cf"]:::config
        ConfigServices["services"]:::config
        ConfigVersion["version.pl"]:::config
        ConfigPaths1["paths.pl"]:::config
        ConfigPaths2["paths.sh"]:::config
    end

    subgraph "Rules Engine Store" 
        direction TB
        RulesFacts["rules/facts"]:::config
        RulesServices["rules/services"]:::config
        RulesTrust["rules/trust"]:::config
        RulesHosttype["rules/hosttype"]:::config
        RulesTodo["rules/todo"]:::config
        RulesDrop["rules/drop"]:::config
    end

    %% Probe Binaries
    subgraph "Probe Binaries (bin/)" 
        direction TB
        BootBinary["boot.satan"]:::c
        NFSCBinary["nfs-chk.satan"]:::c
        FTPBinary["ftp.satan"]:::c
        TCPSBinary["tcpscan.satan"]:::c
        UDPSBinary["udpscan.satan"]:::c
        DNSBinary["dns.satan"]:::c
        RPCBinary["rpc.satan"]:::c
    end

    %% Data Store
    DataStore["Data Store (flat files / satan.db)"]:::db

    %% Flow Connections
    Admin -->|HTTP Request| WebServer
    WebServer -->|CGI exec| CFAction
    WebServer -->|CGI exec| CFForm
    WebServer -->|CGI exec| DataForm
    WebServer -->|CGI exec| MergeAction
    WebServer -->|CGI exec| OpenAction
    WebServer -->|CGI exec| RunAction
    WebServer -->|CGI exec| RunForm
    WebServer -->|CGI exec| MainCGI
    WebServer -->|CGI exec| DocCGI

    CFAction -->|calls| PolicyEngine
    CFForm -->|calls| PolicyEngine
    DataForm -->|calls| PolicyEngine
    MergeAction -->|calls| PolicyEngine
    OpenAction -->|calls| PolicyEngine
    RunAction -->|calls| PolicyEngine
    RunForm -->|calls| PolicyEngine
    MainCGI -->|calls| PolicyEngine
    DocCGI -->|calls| PolicyEngine

    PolicyEngine -->|reads| ConfigCF
    PolicyEngine -->|reads| ConfigServices
    PolicyEngine -->|reads| ConfigVersion
    PolicyEngine -->|reads| ConfigPaths1
    PolicyEngine -->|reads| ConfigPaths2
    PolicyEngine -->|reads| RulesFacts
    PolicyEngine -->|reads| RulesServices
    PolicyEngine -->|reads| RulesTrust
    PolicyEngine -->|reads| RulesHosttype
    PolicyEngine -->|reads| RulesTodo
    PolicyEngine -->|reads| RulesDrop

    PolicyEngine -->|fork/exec| BootBinary
    PolicyEngine -->|fork/exec| NFSCBinary
    PolicyEngine -->|fork/exec| FTPBinary
    PolicyEngine -->|fork/exec| TCPSBinary
    PolicyEngine -->|fork/exec| UDPSBinary
    PolicyEngine -->|fork/exec| DNSBinary
    PolicyEngine -->|fork/exec| RPCBinary

    BootBinary -->|scan| TargetNet
    NFSCBinary -->|scan| TargetNet
    FTPBinary -->|scan| TargetNet
    TCPSBinary -->|scan| TargetNet
    UDPSBinary -->|scan| TargetNet
    DNSBinary -->|scan| TargetNet
    RPCBinary -->|scan| TargetNet

    TargetNet -->|raw facts| PolicyEngine
    PolicyEngine -->|write facts| DataStore

    DataStore -->|read| Reporting
    Reporting -->|generate HTML| Admin

    %% Click Events
    click WebServer "https://github.com/zenfish/satan/tree/master/html/"
    click CFAction "https://github.com/zenfish/satan/blob/master/html/admin/satan_cf_action.pl"
    click CFForm "https://github.com/zenfish/satan/blob/master/html/admin/satan_cf_form.pl"
    click DataForm "https://github.com/zenfish/satan/blob/master/html/data/satan_data_form.pl"
    click MergeAction "https://github.com/zenfish/satan/blob/master/html/data/satan_merge_action.pl"
    click OpenAction "https://github.com/zenfish/satan/blob/master/html/data/satan_open_action.pl"
    click RunAction "https://github.com/zenfish/satan/blob/master/html/running/satan_run_action.pl"
    click RunForm "https://github.com/zenfish/satan/blob/master/html/running/satan_run_form.pl"
    click MainCGI "https://github.com/zenfish/satan/blob/master/html/satan.pl"
    click DocCGI "https://github.com/zenfish/satan/blob/master/html/satan_documentation.pl"
    click Reporting "https://github.com/zenfish/satan/tree/master/html/reporting/"
    click PolicyEngine "https://github.com/zenfish/satan/blob/master/perl/policy-engine.pl"
    click Facts "https://github.com/zenfish/satan/blob/master/perl/facts.pl"
    click InferFacts "https://github.com/zenfish/satan/blob/master/perl/infer_facts.pl"
    click DropFact "https://github.com/zenfish/satan/blob/master/perl/drop_fact.pl"
    click RunSatan "https://github.com/zenfish/satan/blob/master/perl/run-satan.pl"
    click DataScript "https://github.com/zenfish/satan/blob/master/perl/satan-data.pl"
    click Getopts "https://github.com/zenfish/satan/blob/master/perllib/getopts.pl"
    click Ctime "https://github.com/zenfish/satan/blob/master/perllib/ctime.pl"
    click ConfigCF "https://github.com/zenfish/satan/blob/master/config/satan.cf"
    click ConfigServices "https://github.com/zenfish/satan/tree/master/config/services"
    click ConfigVersion "https://github.com/zenfish/satan/blob/master/config/version.pl"
    click ConfigPaths1 "https://github.com/zenfish/satan/blob/master/config/paths.pl"
    click ConfigPaths2 "https://github.com/zenfish/satan/blob/master/config/paths.sh"
    click RulesFacts "https://github.com/zenfish/satan/tree/master/rules/facts"
    click RulesServices "https://github.com/zenfish/satan/tree/master/rules/services"
    click RulesTrust "https://github.com/zenfish/satan/tree/master/rules/trust"
    click RulesHosttype "https://github.com/zenfish/satan/tree/master/rules/hosttype"
    click RulesTodo "https://github.com/zenfish/satan/tree/master/rules/todo"
    click RulesDrop "https://github.com/zenfish/satan/tree/master/rules/drop"
    click BootBinary "https://github.com/zenfish/satan/blob/master/bin/boot.satan"
    click NFSCBinary "https://github.com/zenfish/satan/blob/master/bin/nfs-chk.satan"
    click FTPBinary "https://github.com/zenfish/satan/blob/master/bin/ftp.satan"
    click TCPSBinary "https://github.com/zenfish/satan/blob/master/bin/tcpscan.satan"
    click UDPSBinary "https://github.com/zenfish/satan/blob/master/bin/udpscan.satan"
    click DNSBinary "https://github.com/zenfish/satan/blob/master/bin/dns.satan"
    click RPCBinary "https://github.com/zenfish/satan/blob/master/bin/rpc.satan"

    %% Styles
    classDef external fill:#f5f5f5,stroke:#333,stroke-width:1px;
    classDef ui fill:#c1e1c1,stroke:#2d7f2d,stroke-width:1px;
    classDef perl fill:#add8e6,stroke:#1e487a,stroke-width:1px;
    classDef c fill:#f08080,stroke:#a80000,stroke-width:1px;
    classDef config fill:#fff68f,stroke:#b5a600,stroke-width:1px;
    classDef db fill:#ffcc99,stroke:#b87333,stroke-width:1px;
```
