Overview

offsectoolman is a small, auditable Bash tool manager for offensive-security labs. It codifies tool installation into a single configuration file and automates package-manager checks, installations and per-tool commands. The goal: reproducible lab boots, minimal manual intervention, and transparent operations.

Quickstart

Clone and run from the repo:

git clone https://github.com/ousbaailyas/offsectoolman.git
cd offsectoolman
chmod +x offsectoolman.sh
./offsectoolman.sh -f ./shared/tools.conf --apt --go

Run directly from raw:

bash <(curl -sSL https://raw.githubusercontent.com/ousbaailyas/offsectoolman/master/offsectoolman) -f ./shared/tools.conf

Design goals

• Reproducible: deterministic installs driven by a single config file.

• Minimal & auditable: pure Bash, single script, human-readable logic.

• Composable: per-tool manager mapping (apt, npm, go, pdtm, pip3).

• Safe defaults: explicit confirmation for destructive actions; clear logging.

• Operational clarity: color-coded logs and exit codes for automation.

Configuration model

The manifest (tools.conf) groups tools by package manager:

[apt]
nmap:nmap
masscan:masscan

[npm]
http-server:http-server

[go]
github.com/project/tool:tool

[pdtm]
tool-source:tool-cli

[pip3]
crits:crits

Each entry is source:install-cmd where source is the repository or package name and install-cmd is the CLI command (or package identifier) the manager uses to install it. The script supports a default ./shared/tools.conf and a passed -f file.

Core components

1. CLI parser

   • Parses flags: -f|--file, --apt, --npm, --go, --pdtm, --pip3, -h.

   • Validates presence of required config.

2. Package manager checks

   • Detects manager binaries; offers --install flags to attempt simple bootstrapping where feasible (apt already present on Debian/Ubuntu; others require distro packages or binary downloads).

3. Installer dispatcher

   • For each tool entry: map manager → normalized install command → run idempotent install step.

   • Logs status: installed, skipped, failed.

4. Colorized logger

   • Standardized [OK], [INF], [ERR] messages with exit codes for CI integration.

5. Config-driven flow

   • Supports dry-run mode, verbose logging, and selective manager runs.

Usage examples

• Provision full lab from default manifest:

  ./offsectoolman.sh -f ./shared/tools.conf

• Install only Go and pip3 toolchains:

  ./offsectoolman.sh -f ./shared/tools.conf --go --pip3

• Dry run to validate config:

  ./offsectoolman.sh -f ./shared/tools.conf --dry-run

Implementation notes & behavior

• Idempotence: installers skip items already present (simple existence checks). This reduces side effects during repeated runs.

• Permissions: script prefers running as non-root with sudo where necessary; prompts for elevation when a manager requires root.

• Network: installers assume outbound internet to fetch packages and repos. Provide mirrored sources for air-gapped labs.

• Error handling: failures for individual tools are non-fatal by default; a global --fail-fast flag will abort on first error for stricter CI use.

• Extensibility: add new manager handlers by implementing a small install_<manager>() function and mapping it in the dispatcher.

Security & safety considerations

• Do not run on production systems — intended for isolated lab environments.

• Audit tools.conf before running — manifests control remote installs.

• Avoid running raw from the network in sensitive contexts; prefer cloning and inspecting the script.

• Least privilege: prefer non-root actions and limit sudo use to necessary steps.

Integration & workflows

• CI / IaC: use offsectoolman in ephemeral CI runners to provision test containers with tooling.

• Red-team kit: include a snapshot of tools.conf in engagement repositories to ensure consistent tooling across operators.

• Bootstrap images: generate prebuilt VM/container images after a successful run to speed future deployments.

Example pipeline snippet:

# CI runner
./offsectoolman.sh -f ./shared/tools.conf --apt --go --npm --pip3 --fail-fast
tar -czf snakeeater-lab-$(date +%F).tar.gz /opt/lab

Testing & validation

• Unit-test config parsing for edge cases (empty entries, malformed lines).

• Validate installer idempotence across distro variations (Debian, Ubuntu, Kali, Alpine where possible).

• Run integration tests in disposable containers to catch package name differences and network failures.

Extension ideas

• JSON/YAML manifest with richer metadata (version pinning, checksums).

• Plugin system for custom install hooks (post-install configuration).

• Parallel installer with rate-limiting to speed large manifests.

• Signed manifests and checksum verification to ensure provenance.

Example internal flow (concise)

1. Load and validate tools.conf.

2. Detect requested managers and availability.

3. For each manager: iterate tools → check presence → run install command if missing → log result.

4. Emit summary and exit code.

Best practices

• Maintain a lightweight canonical manifest per engagement.

• Pin versions where reproducibility matters.

• Keep the script auditable and small; avoid embedding large install blobs.

• Use --dry-run in CI for validation before applying changes.

Contribution & maintainers

• Keep PRs focused and small.

• Add tests for new manager handlers and new config syntax.

• Document expected platform compatibility (tested on Debian/Ubuntu family).

License & ethics

• MIT License. Use responsibly and only on permitted systems.