Scaffold a new module

Adding a module is more invasive than adding a tool — it requires edits in several places.

1. Choose name + prefix

Pick a short module name and a SCREAMING_SNAKE prefix. Examples already used: misc/MISC, networking/NET, recon/RECON, web/WEB, crypto/CRYPTO, pwn/PWN, reversing/RE, forensics/FORENSICS, enterprise/ENTERPRISE, wireless/WIRELESS, cracking/CRACKING, stego/STEGO, cloud/CLOUD, containers/CONTAINER, blueteam/BLUETEAM, mobile/MOBILE, blockchain/BLOCKCHAIN, llm/LLM.

2. Create modules/<name>.sh

Template:

Mirror an existing module such as modules/stego.sh:

#!/bin/bash
# shellcheck disable=SC2034  # Arrays are consumed by scripts that source this module
# Module: <Title>
# <one-line description>

<PREFIX>_PACKAGES=()
<PREFIX>_PIPX=()
<PREFIX>_GO=()                # "module/path@latest" entries
<PREFIX>_GO_BINS=()           # binary name per <PREFIX>_GO entry
<PREFIX>_CARGO=()
<PREFIX>_GEMS=()
<PREFIX>_GIT=()               # "name=https://github.com/owner/repo.git" entries
<PREFIX>_GIT_NAMES=()         # the names from <PREFIX>_GIT

install_module_<name>() {
    install_apt_batch "<Title> - Packages" "${<PREFIX>_PACKAGES[@]}"
    install_pipx_batch "<Title> - Python" "${<PREFIX>_PIPX[@]}"
    install_go_batch "<Title> - Go" "${<PREFIX>_GO[@]}"
    install_cargo_batch "<Title> - Rust" "${<PREFIX>_CARGO[@]}"
    install_gem_batch "<Title> - Ruby" "${<PREFIX>_GEMS[@]}"
    install_git_batch "<Title> - Git" "${<PREFIX>_GIT[@]}"
}

Binary releases go in BINARY_RELEASES_<MODULE> in lib/installers.sh, installed with install_binary_releases "${BINARY_RELEASES_<MODULE>[@]}".

Mark executable: chmod +x modules/<name>.sh.

3. Register the module

lib/common.sh → ALL_MODULES

Append the new module name to the ALL_MODULES array.

lib/common.sh → MODULE_DESCRIPTIONS

Add a one-line description (mirrored to MCP).

install.sh

install.sh sources modules conditionally — verify the dispatcher case statement covers <name>. Most installers iterate ALL_MODULES so no change needed.

4. Mirror to MCP server

In mcp_server/tools_db.py:

MODULE_DESCRIPTIONS = {
    ...
    "<name>": "<same description as common.sh>",
}

Run python3 scripts/validate_mcp_sync.py after.

5. Add at least one tool

A module with empty arrays is dead code. Use the add-tool skill to add ≥1 tool before merging.

6. Add a profile (optional)

If the module deserves its own profile (e.g., myprofile.conf):

# Profile: <one-line description>
MODULES="misc <name>"
SKIP_HEAVY=true
ENABLE_DOCKER=false
INCLUDE_C2=false

The first-line # Profile: header is the description, and the flags must be true/false. Mirror the profile in mcp_server/profiles.py (PROFILES), then run bash scripts/validate_profiles.sh and python3 scripts/validate_mcp_sync.py.

7. Validate

Use the validate-all skill — must show zero errors before merging.