Toolkit Manager

Toolkit Manager

The toolkit manager lets you install Git-based security tools onto a VM, and save them to a registry so every new VM can get the same set automatically. No more re-cloning your favorite tools by hand on each fresh box.

Install a toolkit on a running VM

sudo bull toolkit <vm-name> <git-url>

The VM must be running. Bull clones the repo to /opt/toolkits/<name> inside the VM and auto-detects how to install it:

1. Clone (or git pull --ff-only if it already exists, re-cloning if the pull fails).
2. If the repo has an install.sh, run it.
3. Otherwise, if it has a setup.py, install Python requirements.
4. chown the result back to the VM user.

The registry

Saved toolkits live in ${BULL_HOME}/toolkits.json. From the interactive menu you can save, rename, and remove entries, and Bull offers to install all saved toolkits when you create a new VM.

Registry entries are just a name and a URL:

{
  "toolkits": [
    { "name": "my-tool", "url": "https://github.com/owner/my-tool.git" }
  ]
}

Saving is idempotent: saving an existing name updates its URL instead of duplicating it.

URL and name validation

Because toolkits are installed over vagrant ssh -c, Bull validates input before it ever reaches the VM:

• URLs must start with https://, http://, git://, git@, or ssh://, and must not contain shell metacharacters (`, ', ", $, (, ), ;, |, &, <, >). This blocks command injection.
• Names (derived from the repo basename) must be alphanumeric plus hyphens and underscores.

Making a tool Bull-compatible

If you maintain a security tool and want one-click installs to work:

1. Add an install.sh at the repo root that handles its own dependencies.
2. Make it idempotent (safe to run more than once).
3. Use apt-get install -y for system packages.
4. Never require interactive input.

Minimal example:

#!/usr/bin/env bash
set -uo pipefail

apt-get install -y python3 python3-pip 2>/dev/null || true
pip3 install -r requirements.txt 2>/dev/null || true

echo "[+] Tool installed to $(pwd)"

Adding a new install pattern

Bull currently understands install.sh and setup.py. To teach it another (say Makefile or go install), edit install_toolkit() in lib/toolkits.sh and add an elif branch after the setup.py check. See Adding a Tool in the repo for the full guide and contribution checklist.