# orange-cyberdefense/arsenal architecture

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

- Interactive diagram: https://gitdiagram.com/orange-cyberdefense/arsenal
- Repository: https://github.com/orange-cyberdefense/arsenal

## Overview

##### Project type and purpose
- Arsenal is an open-source command-line tool (CLI) written in Python.
- Its purpose is to index, search, display and auto-inject pentest “cheat-sheet” commands into any shell or tmux pane.

##### File structure
- Top-level files and scripts: run, addalias.sh, pushtopip.sh, setup.py, pyproject.toml, requirements.txt.
- Main package: “arsenal/” contains:
- app.py and __main__.py: entry points
- modules/: code organized by responsibility (cheat.py, command.py, config.py, gui.py, check.py)
- data/cheats/: hierarchical Markdown/YAML cheat-sheet files
- A “my_cheats” folder for user-provided cheat sheets.
- CI config in .github/workflows.
- README, LICENSE, PKGBUILD, MANIFEST.in indicate packaging and distribution.

##### README for additional insights
- Arsenal reads .md/.rst/.yml formats, supports global variables, fzf integration, tmux pane injection via TIOCSTI ioctl.
- It uses Python libraries: PyYAML, possibly prompt_toolkit or curses for UI.
- Extensions: external cheat-paths via config.

##### Main components and interactions
a. User Interface
- CLI front-end, parses arguments and keypresses.
- Optionally invokes fzf (external fuzzy-finder).
b. Configuration Manager
- Loads CHEATS_PATHS, global variables, prefix settings.
c. Cheat Loader
- Scans file system folders (data/cheats, my_cheats, ~/.cheats).
- Parses Markdown, RST, YAML into in-memory structures.
d. Search & Selection Engine
- Hands off cheat list to fzf or built-in selector (gui module).
e. Command Builder
- Substitutes variables, default values, prefixes.
f. Injection Engine
- Uses termios.TIOCSTI via fcntl.ioctl to emulate keystrokes.
- Integrates with tmux (splitting panes, sending to other pane).
- Falls back to direct TTY IO if needed.
g. External Shell/Environment
- Any POSIX shell; commands appear in shell history.
- Optionally tmux server.

##### Architectural patterns and design principles
- Modular layering: separation between CLI parsing, configuration, data loading, search UI, command injection.
- Plugin/extension point for additional cheat paths.
- Single-process, synchronous flow (no microservices).
- Uses external tools (fzf, tmux) rather than rebuilding functionality.
- Lightweight, file-system as primary datastore.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::external
    subgraph "Core Modules"
        CLI["CLI Parser"]:::core
        Config["Config Manager"]:::core
        Loader["Cheat Loader"]:::core
        Search["Search/UI Module"]:::core
        Builder["Command Builder"]:::core
        Injector["Injection Engine"]:::core
    end
    subgraph "Data Sources"
        FileSystem[(Cheats File System)]:::data
        MyCheats[(my_cheats)]:::data
    end
    subgraph "External Tools"
        FZF["fzf"]:::external
        Tmux["tmux"]:::external
    end
    Shell["Shell/Tmux"]:::external
    subgraph "Entry & Packaging"
        run("run"):::packaging
        setup("setup.py"):::packaging
        pyproject("pyproject.toml"):::packaging
        requirements("requirements.txt"):::packaging
        manifest("MANIFEST.in"):::packaging
        PKGBUILD("PKGBUILD"):::packaging
        CI(".github/workflows/lint_python.yml"):::packaging
    end

    User -->|"CLI Input"| CLI
    CLI -->|"load config"| Config
    Config -->|"paths & settings"| Loader
    Loader -->|"scan cheats"| FileSystem
    Loader -->|"scan user cheats"| MyCheats
    Loader -->|"cheat metadata"| Search
    Search -->|"fuzzy selection"| FZF
    Search -->|"selected cheat"| Builder
    Builder -->|"built command"| Injector
    Injector -->|"inject keystrokes"| Shell
    Injector -->|"inject via tmux"| Tmux
    Tmux -->|"pane communication"| Shell

    click CLI "https://github.com/orange-cyberdefense/arsenal/blob/master/arsenal/__main__.py"
    click CLI "https://github.com/orange-cyberdefense/arsenal/blob/master/arsenal/app.py"
    click Config "https://github.com/orange-cyberdefense/arsenal/blob/master/arsenal/modules/config.py"
    click Loader "https://github.com/orange-cyberdefense/arsenal/blob/master/arsenal/modules/cheat.py"
    click FileSystem "https://github.com/orange-cyberdefense/arsenal/tree/master/arsenal/data/cheats/"
    click Search "https://github.com/orange-cyberdefense/arsenal/blob/master/arsenal/modules/gui.py"
    click Builder "https://github.com/orange-cyberdefense/arsenal/blob/master/arsenal/modules/command.py"
    click Injector "https://github.com/orange-cyberdefense/arsenal/blob/master/arsenal/modules/check.py"
    click run "https://github.com/orange-cyberdefense/arsenal/tree/master/run"
    click setup "https://github.com/orange-cyberdefense/arsenal/blob/master/setup.py"
    click pyproject "https://github.com/orange-cyberdefense/arsenal/blob/master/pyproject.toml"
    click requirements "https://github.com/orange-cyberdefense/arsenal/blob/master/requirements.txt"
    click manifest "https://github.com/orange-cyberdefense/arsenal/blob/master/MANIFEST.in"
    click PKGBUILD "https://github.com/orange-cyberdefense/arsenal/tree/master/PKGBUILD"
    click CI "https://github.com/orange-cyberdefense/arsenal/blob/master/.github/workflows/lint_python.yml"

    classDef core fill:#ADD8E6,stroke:#000
    classDef external fill:#98FB98,stroke:#000
    classDef data fill:#FFA500,stroke:#000
    classDef packaging fill:#D8BFD8,stroke:#000
```
