# devdanzin/fusil architecture

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

- Interactive diagram: https://gitdiagram.com/devdanzin/fusil
- Repository: https://github.com/devdanzin/fusil

## Overview

##### Project type and purpose
- Type: Open-source Python fuzzing framework with a plugin-style “fusil-…” fuzzer CLI layer.
- Purpose: Provide a library (fusil/) of multi-agent system components and probes to launch, monitor, and score fuzzing sessions against arbitrary target programs. It ships with ready-to-run fuzzers in fuzzers/.

##### File structure
- Top-level directories:
- fusil/: core Python library implementing application setup, multi-agent system (MAS), probes (process, network, file, syslog, CPU), manglers, session management, logging, utilities.
- fuzzers/: small executable wrappers (“fusil-foo”) invoking fusil library against a specific target.
- doc/: Sphinx sources describing architecture, configuration, components, how-tos.
- tests/: unit and integration tests for command-line parsing, file-watch, help outputs, etc.
- Configuration/build files: setup.py, setup.cfg, MANIFEST.in for packaging; .gitignore; doc/Makefile.

##### Insights from README
- Fusil creates isolated session directories, limits resources, redirects output, and launches probes.
- Architecture: multi-agent system where agents (process agent, network agent, mangle agent, logger agent, etc.) cooperate via mailboxes.
- CLI fuzzers call fusil.application to configure and start sessions.

##### Detailed guidance
- How configuration flows from CLI → Config → Application → Agents.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer" 
        direction TB
        CLI["fusil-<project> Executable"]:::cli
    end
    click CLI "https://github.com/devdanzin/fusil/tree/main/fuzzers/"

    %% Application Manager & Config
    subgraph "Fusil Core" 
        direction TB
        AM["Application Manager\n(fusil/application.py)"]:::core
        click AM "https://github.com/devdanzin/fusil/blob/main/fusil/application.py"

        subgraph "Configuration" 
            direction TB
            Config["Config Module\n(fusil/config.py)"]:::core
            click Config "https://github.com/devdanzin/fusil/blob/main/fusil/config.py"
            CLIParser["CLI Parser\n(fusil/cmd_help_parser.py)"]:::core
            click CLIParser "https://github.com/devdanzin/fusil/blob/main/fusil/cmd_help_parser.py"
        end

        subgraph "Session Manager" 
            direction TB
            SM["Session Manager\n(fusil/session.py)"]:::core
            click SM "https://github.com/devdanzin/fusil/blob/main/fusil/session.py"
            SMAgent["Session Agent\n(fusil/session_agent.py)"]:::core
            click SMAgent "https://github.com/devdanzin/fusil/blob/main/fusil/session_agent.py"
            SDir["Session Directory\n(fusil/session_directory.py)"]:::storage
            click SDir "https://github.com/devdanzin/fusil/blob/main/fusil/session_directory.py"
        end

        subgraph "MAS Core" 
            direction TB
            AgentCore["Agent Core\n(fusil/mas/)"]:::core
            click AgentCore "https://github.com/devdanzin/fusil/tree/main/fusil/mas/"
            A1["agent.py"]:::core
            click A1 "https://github.com/devdanzin/fusil/blob/main/fusil/mas/agent.py"
            A2["mailbox.py"]:::core
            click A2 "https://github.com/devdanzin/fusil/blob/main/fusil/mas/mailbox.py"
            A3["message.py"]:::core
            click A3 "https://github.com/devdanzin/fusil/blob/main/fusil/mas/message.py"
            A4["univers.py"]:::core
            click A4 "https://github.com/devdanzin/fusil/blob/main/fusil/mas/univers.py"
        end

        subgraph "Agents" 
            direction TB
            subgraph "Process Agent" 
                direction TB
                PA["Process Agent"]:::agent
                click PA "https://github.com/devdanzin/fusil/tree/main/fusil/process/"
                P1["create.py"]:::agent
                click P1 "https://github.com/devdanzin/fusil/blob/main/fusil/process/create.py"
                P2["watch.py"]:::agent
                click P2 "https://github.com/devdanzin/fusil/blob/main/fusil/process/watch.py"
                P3["cpu_probe.py"]:::agent
                click P3 "https://github.com/devdanzin/fusil/blob/main/fusil/process/cpu_probe.py"
                P4["time_watch.py"]:::agent
                click P4 "https://github.com/devdanzin/fusil/blob/main/fusil/process/time_watch.py"
                P5["attach.py"]:::agent
                click P5 "https://github.com/devdanzin/fusil/blob/main/fusil/process/attach.py"
                P6["stdout.py"]:::agent
                click P6 "https://github.com/devdanzin/fusil/blob/main/fusil/process/stdout.py"
            end

            subgraph "Network Agent" 
                direction TB
                NA["Network Agent"]:::agent
                click NA "https://github.com/devdanzin/fusil/tree/main/fusil/network/"
                N1["http_server.py"]:::agent
                click N1 "https://github.com/devdanzin/fusil/blob/main/fusil/network/http_server.py"
                N2["http_request.py"]:::agent
                click N2 "https://github.com/devdanzin/fusil/blob/main/fusil/network/http_request.py"
                N3["tcp_server.py"]:::agent
                click N3 "https://github.com/devdanzin/fusil/blob/main/fusil/network/tcp_server.py"
                N4["tcp_client.py"]:::agent
                click N4 "https://github.com/devdanzin/fusil/blob/main/fusil/network/tcp_client.py"
            end

            FWA["File Watch Agent\n(fusil/file_watch.py)"]:::agent
            click FWA "https://github.com/devdanzin/fusil/blob/main/fusil/file_watch.py"

            subgraph "Mangle Agent" 
                direction TB
                MA["Mangle Agent"]:::agent
                click MA "https://github.com/devdanzin/fusil/blob/main/fusil/mangle_agent.py"
                AM1["auto_mangle.py"]:::agent
                click AM1 "https://github.com/devdanzin/fusil/blob/main/fusil/auto_mangle.py"
                IM["incr_mangle.py"]:::agent
                click IM "https://github.com/devdanzin/fusil/blob/main/fusil/incr_mangle.py"
            end

            LogA["Logging Agent\n(fusil/application_logger.py)"]:::agent
            click LogA "https://github.com/devdanzin/fusil/blob/main/fusil/application_logger.py"

            ScoreA["Scoring Agent\n(fusil/score.py)"]:::agent
            click ScoreA "https://github.com/devdanzin/fusil/blob/main/fusil/score.py"
        end

        DirUtil["Directory Utils\n(fusil/directory.py)"]:::core
        click DirUtil "https://github.com/devdanzin/fusil/blob/main/fusil/directory.py"
    end

    %% External & Storage
    SDirCyl(("Session Directory")):::storage
    Target["Target Process"]:::external

    %% Relationships
    CLI -->|invokes| AM
    CLI -->|parses| Config
    Config --> AM
    AM -->|starts| SM
    SM -->|uses| AgentCore
    AgentCore --> Agents
    Agents -->|register| A2
    Agents -->|exchange messages| A4
    PA -->|launch| Target
    NA -->|intercept| Target
    FWA -->|monitor files| SDirCyl
    MA -->|write inputs| SDirCyl
    LogA -->|collect logs| SDirCyl
    ScoreA -->|feedback| AM
    SM -->|reads/writes| SDirCyl
    DirUtil --> SDirCyl

    %% Loop indicator
    SM -->|score loop| AM

    %% Connection to session directory node
    SDir --> SDirCyl

    %% CLI to core boundary
    CLI -.-> AM

    %% Styles
    classDef core fill:#D6EAF8,stroke:#1F618D,color:#1B4F72;
    classDef agent fill:#ABEBC6,stroke:#196F3D,color:#145A32;
    classDef external fill:#F5B041,stroke:#B9770E,color:#7E5109;
    classDef storage fill:#DDDDDD,stroke:#555555,color:#333333;
    classDef cli fill:#F5B7B1,stroke:#C0392B,color:#78281F;
```
