# ullaakut/nmap architecture

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

- Interactive diagram: https://gitdiagram.com/ullaakut/nmap
- Repository: https://github.com/ullaakut/nmap

## Overview

##### Project type and purpose
- This is a Go library that provides idiomatic bindings to the Nmap network scanner.
- Purpose: allow Go programs to build and run Nmap scans, parse the XML output into Go structs, and offer filtering/streaming/async capabilities.

##### File structure
- Top-level files:
- errors.go, xml.go, nmap.go, iflist.go — core logic for building options, invoking Nmap, parsing XML, listing interfaces
- options*.go — each file defines a category of Nmap command-line options (host discovery, OS detection, scripts, timing, etc.)
- pkg/osfamilies — definitions of OS families (helper enums)
- examples/ — sample programs illustrating use of the API (basic scans, async, progress, streaming, filtering)
- tests/ — integration tests with fake_nmap shell scripts and sample XML files
- CI config (.github/workflows), Go linting (.golangci.yml), module files (go.mod, go.sum)

##### Key insights from the README
- The library wraps every native Nmap option in a WithXXX function, uses context for timeouts, returns Go structs + warnings.
- Supports synchronous, asynchronous, progress streaming, output to io.Writer, file output.
- Encourages filtering by host/port and integrates with other tools (e.g., Cameradar).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client Application"]:::client

    %% Library
    subgraph "Go Nmap Library"
        subgraph "Options Builder"
            OB1["Host Discovery"]:::library
            OB2["OS Detection"]:::library
            OB3["Misc Options"]:::library
            OB4["Output Options"]:::library
            OB5["Port Order"]:::library
            OB6["Scan Techniques"]:::library
            OB7["Script Scan"]:::library
            OB8["Service Version"]:::library
            OB9["Target Spec"]:::library
            OB10["Timing Performance"]:::library
            OB11["Firewall Spoofing"]:::library
        end
        Executor["Scanner Executor"]:::library
        Parser["XML Parser"]:::library
        Error["Error Handling"]:::library
        IFACE["Network Interface Listing"]:::library
        OSFAM["OS Families"]:::library
        Filter["Filter & Stream API"]:::interfaces
    end

    %% External
    NMAP["External Nmap Binary"]:::external
    Network["Network Targets"]:::external

    subgraph "Test Harness"
        Fake1["fake_nmap.sh"]:::external
        Fake2["fake_nmap_delay.sh"]:::external
        Fake3["fake_nmap_iflist.sh"]:::external
        XMLFixtures["Sample XML Fixtures"]:::external
    end

    subgraph "CI/CD Pipeline"
        Build[".github/workflows/build.yml"]:::external
        TestCI[".github/workflows/test.yml"]:::external
        LintCI[".golangci.yml"]:::external
    end

    %% Flows
    Client -->|"NewScanner()/WithXXX"| OB1
    OB1 & OB2 & OB3 & OB4 & OB5 & OB6 & OB7 & OB8 & OB9 & OB10 & OB11 --> Executor
    Executor -->|"os/exec invokes with -oX - and flags"| NMAP
    NMAP -->|"XML stdout"| Parser
    Parser -->|"Go Structs"| Filter
    Filter -->|"Filtered Results"| Client
    Parser -->|"Warnings/Error"| Error
    Client -->|"io.Writer/channel"| Filter

    Fake1 & Fake2 & Fake3 -->|"exec fake binary"| Parser
    XMLFixtures -->|"XML input"| Parser

    Build & TestCI & LintCI -->|"runs build/lint/tests"| Client

    %% Click Events
    click OB1 "https://github.com/ullaakut/nmap/blob/master/optionsHostDiscovery.go"
    click OB2 "https://github.com/ullaakut/nmap/blob/master/optionsOS.go"
    click OB3 "https://github.com/ullaakut/nmap/blob/master/optionsMisc.go"
    click OB4 "https://github.com/ullaakut/nmap/blob/master/optionsOutput.go"
    click OB5 "https://github.com/ullaakut/nmap/blob/master/optionsPortOrder.go"
    click OB6 "https://github.com/ullaakut/nmap/blob/master/optionsScanTechniques.go"
    click OB7 "https://github.com/ullaakut/nmap/blob/master/optionsScriptScan.go"
    click OB8 "https://github.com/ullaakut/nmap/blob/master/optionsServiceVersion.go"
    click OB9 "https://github.com/ullaakut/nmap/blob/master/optionsTargetSpecification.go"
    click OB10 "https://github.com/ullaakut/nmap/blob/master/optionsTimingPerformance.go"
    click OB11 "https://github.com/ullaakut/nmap/blob/master/optionsFirewallSpoofing.go"
    click Executor "https://github.com/ullaakut/nmap/blob/master/nmap.go"
    click Parser "https://github.com/ullaakut/nmap/blob/master/xml.go"
    click Error "https://github.com/ullaakut/nmap/blob/master/errors.go"
    click IFACE "https://github.com/ullaakut/nmap/blob/master/iflist.go"
    click OSFAM "https://github.com/ullaakut/nmap/blob/master/pkg/osfamilies/os_families.go"
    click Fake1 "https://github.com/ullaakut/nmap/blob/master/tests/scripts/fake_nmap.sh"
    click Fake2 "https://github.com/ullaakut/nmap/blob/master/tests/scripts/fake_nmap_delay.sh"
    click Fake3 "https://github.com/ullaakut/nmap/blob/master/tests/scripts/fake_nmap_iflist.sh"
    click XMLFixtures "https://github.com/ullaakut/nmap/blob/master/tests/xml/scan_base.xml"
    click Build "https://github.com/ullaakut/nmap/blob/master/.github/workflows/build.yml"
    click TestCI "https://github.com/ullaakut/nmap/blob/master/.github/workflows/test.yml"
    click LintCI "https://github.com/ullaakut/nmap/blob/master/.golangci.yml"

    %% Styles
    classDef library fill:#f9f,stroke:#333,stroke-width:1px
    classDef external fill:#bbf,stroke:#333,stroke-width:1px
    classDef client fill:#bfb,stroke:#333,stroke-width:1px
    classDef interfaces fill:#fbf,stroke:#333,stroke-width:1px
```
