Extending Kraken

Extending Kraken

New tentacles can be added in a handful of lines. There are three ways to extend Kraken: add a tool to an existing module, integrate a git-based tool, or create a whole new module.

1. Add a tool to an existing module

Write a helper in the relevant lib/modules/*.sh file and call it from the module's entry point.

# In lib/modules/recon.sh
_kraken_recon_amass() {
    local target="$1"
    local out_file="$2"
    ensure_command "amass" "install: snap install amass" || return 0
    log_step "Running amass passive enumeration..."
    amass enum -passive -d "${target}" -o "${out_file}" 2>/dev/null
    log_success "Amass results saved"
}

Then call it from kraken_recon_run:

_kraken_recon_amass "${target}" "${recon_dir}/amass.txt"

ensure_command returns non-zero and the helper exits early if the tool is missing, the rest of the module keeps running.

2. Integrate a git-based tool

When a tool lives in a GitHub repo rather than a package, use ensure_repo. It clones on first use and runs an optional post-install command.

ensure_repo \
    "https://github.com/carlospolop/PEASS-ng.git" \
    "${KRAKEN_OUTPUT_DIR}/tools/peass" \
    "" || return 0

With Python dependencies:

ensure_repo \
    "https://github.com/example/tool.git" \
    "/opt/tool" \
    "pip3 install -r /opt/tool/requirements.txt" || return 0

3. Create a whole new module

3.1 Create the file

lib/modules/postexploit.sh:

#!/usr/bin/env bash
# Kraken module: post-exploitation tooling.

if [[ -n "${KRAKEN_MODULE_POSTEXPLOIT_LOADED:-}" ]]; then
    return 0
fi
KRAKEN_MODULE_POSTEXPLOIT_LOADED=1

kraken_postexploit_run() {
    kraken_clear_screen
    log_step "Launching post-exploitation module..."
    echo

    local label
    label=$(prompt_value "Tag for this run (e.g., host_alpha)")
    if ! kraken_valid_target "${label}"; then
        log_error "Invalid or empty tag"; press_enter_to_continue; return
    fi

    local out_dir="${KRAKEN_OUTPUT_DIR}/postexploit_${label}"
    mkdir -p "${out_dir}"

    # ... your steps here ...

    echo
    kraken_print_separator "─"
    log_success "Post-exploitation complete!"
    printf '%sResults saved in:%s %s\n\n' "${BRIGHT_BLUE}" "${RESET}" "${out_dir}"
    press_enter_to_continue
}

3.2 Wire it into the entry point

In kraken.sh, source the file and add a case to handle_selection:

source "${KRAKEN_ROOT}/lib/modules/postexploit.sh"
# ...
6) kraken_postexploit_run ;;

3.3 Add it to the menu

In lib/ui.sh, inside kraken_display_menu:

${BRIGHT_MAGENTA}║${RESET}  ${BRIGHT_CYAN}[6]${RESET} Post-Exploitation Module

3.4 Register it in the CI smoke test

Add kraken_postexploit_run to the expected array in .github/workflows/ci.yml.

Conventions (Do / Don't)

Don't	Do
echo -e "${RED}error${RESET}"	log_error "error"
read -rp "target: " target	target=$(prompt_value "Enter target")
trust raw input	kraken_valid_target "${target}" || return
command -v nmap checks inline	ensure_command "nmap" "hint" || return 0
local x=$(cmd)	local x; x=$(cmd)
raw git clone in a module	ensure_repo "$url" "$dest"
set -e in a module	let the entry point keep set -uo pipefail
bare globals like OUTPUT_DIR	use KRAKEN_OUTPUT_DIR
forget the KRAKEN_MODULE_*_LOADED guard	always include it

Testing before a PR

bash -n lib/modules/your_module.sh
shellcheck lib/modules/your_module.sh   # uses repo .shellcheckrc
bash kraken.sh --help                   # source chain must load cleanly

CI re-runs all three checks plus the smoke test on every push. See Architecture and Contributing.