Skip to content

Building 70 Projects ranging from beginner to advanced so anyone can — learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company 👇

11.2 KB
Raw Blame
#!/usr/bin/env bash
# ©AngelaMos | 2026
# install.sh

set -euo pipefail

REPO_OWNER="CarterPerez-dev"
REPO_NAME="lisdex"
BINARY="lisdex"
TAGLINE="keyless memory-corruption scanner for C/C++ parsers"
REPO_URL="https://github.com/${REPO_OWNER}/${REPO_NAME}.git"
INSTALL_DIR="${LISDEX_INSTALL_DIR:-$HOME/.local/bin}"
DEFAULT_BRANCH="${LISDEX_BRANCH:-main}"
MIN_RUST="1.97"
VERIFIED_AFL="5.02c"
SKIP_AFL=0

if [ -t 2 ] && [ -z "${NO_COLOR:-}" ]; then
    BOLD=$'\033[1m'; DIM=$'\033[2m'; RED=$'\033[31m'; GREEN=$'\033[32m'
    YELLOW=$'\033[33m'; CYAN=$'\033[36m'; MAGENTA=$'\033[35m'; RESET=$'\033[0m'
else
    BOLD=""; DIM=""; RED=""; GREEN=""; YELLOW=""; CYAN=""; MAGENTA=""; RESET=""
fi

info() { printf '%s\n' "  ${CYAN}+${RESET} $*" >&2; }
ok()   { printf '%s\n' "  ${GREEN}+${RESET} $*" >&2; }
warn() { printf '%s\n' "  ${YELLOW}!${RESET} $*" >&2; }
die()  { printf '%s\n' "  ${RED}x $*${RESET}" >&2; exit 1; }
header(){ printf '\n%s\n\n' "${BOLD}${CYAN}--- $* ---${RESET}" >&2; }
have() { command -v "$1" >/dev/null 2>&1; }

trap 'printf "%s\n" "${RED}x install failed${RESET}" >&2' ERR
TMP_DIR=""
cleanup() { [ -n "$TMP_DIR" ] && rm -rf "$TMP_DIR"; return 0; }
trap cleanup EXIT

banner() {
    printf '%s' "${BOLD}${MAGENTA}" >&2
    cat >&2 <<'ART'
   _     ___ ____  ____  _______  __
  | |   |_ _/ ___||  _ \| ____\ \/ /
  | |    | |\___ \| | | |  _|  \  /
  | |___ | | ___) | |_| | |___ /  \
  |_____|___|____/|____/|_____/_/\_\
ART
    printf '%s\n' "${RESET}" >&2
    printf '%s\n' "  ${DIM}${TAGLINE}${RESET}" >&2
}

SUDO=""
if [ "$(id -u)" -ne 0 ]; then
    if have sudo; then SUDO="sudo"; fi
fi

pkg_install() {
    if   have apt-get; then
        $SUDO apt-get update -y >/dev/null 2>&1 || warn "apt update had errors; continuing"
        $SUDO apt-get install -y --no-install-recommends "$@"
    elif have dnf;    then $SUDO dnf install -y "$@"
    elif have pacman; then $SUDO pacman -S --needed --noconfirm "$@"
    elif have zypper; then $SUDO zypper install -y "$@"
    elif have apk;    then $SUDO apk add "$@"
    elif have brew;   then brew install "$@"
    else die "no known package manager. Install manually: $*"; fi
}

pkg_try() {
    if pkg_install "$@" >/dev/null 2>&1; then return 0; fi
    return 1
}

download() {
    if   have curl; then curl -fsSL "$1" -o "$2" || return 1
    elif have wget; then wget -qO "$2" "$1" || return 1
    else die "need curl or wget"; fi
}

usage() {
    cat >&2 <<USAGE
install.sh — install ${BINARY}

  ./install.sh [options]
  curl -fsSL https://angelamos.com/${BINARY}/install.sh | bash

options:
  --prefix DIR   install dir (default: ${INSTALL_DIR})
  --skip-afl     do not try to install AFL++; ${BINARY} still analyses and reports,
                 but 'build', 'fuzz', 'corpus' and 'minimize' need it
  -h, --help     this help
USAGE
}

while [ $# -gt 0 ]; do
    case "$1" in
        --prefix) INSTALL_DIR="$2"; shift 2 ;;
        --prefix=*) INSTALL_DIR="${1#*=}"; shift ;;
        --skip-afl) SKIP_AFL=1; shift ;;
        -h|--help) usage; exit 0 ;;
        *) die "unknown option: $1 (try --help)" ;;
    esac
done

OS="$(uname -s)"; ARCH="$(uname -m)"
case "$OS" in
    Linux) OS="linux" ;;
    Darwin) OS="darwin" ;;
    MINGW*|MSYS*|CYGWIN*) die "Windows unsupported. Use WSL: this tool drives AFL++, which is Linux-first." ;;
    *) die "unsupported OS: $OS" ;;
esac
case "$ARCH" in
    x86_64|amd64) ARCH="amd64" ;;
    aarch64|arm64) ARCH="arm64" ;;
    *) die "unsupported arch: $ARCH" ;;
esac

resolve_repo() {
    local self="${BASH_SOURCE[0]:-}"
    if [ -f "./Cargo.toml" ] && [ -d "./crates/${BINARY}" ]; then pwd; return; fi
    if [ -n "$self" ] && [ -f "$(dirname "$self")/Cargo.toml" ]; then
        (cd "$(dirname "$self")" && pwd); return
    fi
    if ! have git; then
        warn "git missing — installing it"
        pkg_install git
    fi
    have git || die "could not install git; install it then re-run"
    local cache="${XDG_CACHE_HOME:-$HOME/.cache}/${BINARY}"
    if [ -d "$cache/.git" ]; then
        info "updating cached clone at $cache"
        git -C "$cache" pull --ff-only --quiet 2>/dev/null || warn "pull failed; using existing clone"
    else
        info "cloning ${REPO_URL}"
        local clone_err=""
        if ! clone_err="$(GIT_TERMINAL_PROMPT=0 git clone --depth 1 \
            --branch "$DEFAULT_BRANCH" --quiet "$REPO_URL" "$cache" 2>&1)"; then
            case "$clone_err" in
                *"Could not resolve host"*|*"unable to access"*|*"Connection"*|*"timed out"*|*"Network"*)
                    die "cannot reach the host for ${REPO_URL}: check the network or a proxy" ;;
                *"Remote branch"*|*"Could not find remote branch"*)
                    die "${REPO_URL} has no branch named ${DEFAULT_BRANCH}; set LISDEX_BRANCH to the one it uses" ;;
                *"not found"*|*"Not Found"*|*"not exist"*|*"Authentication"*|*"could not read Username"*|*"Permission denied"*)
                    die "cannot read ${REPO_URL}: it is missing, private, or renamed, and the host will not say which. If you have a checkout, run install.sh from inside it instead" ;;
                *)
                    die "clone failed from ${REPO_URL}: ${clone_err}" ;;
            esac
        fi
    fi
    printf '%s\n' "$cache"
}

version_at_least() {
    [ "$(printf '%s\n%s\n' "$2" "$1" | sort -V | head -1)" = "$2" ]
}

need_toolchain() {
    if ! have cargo; then
        info "installing Rust via rustup"
        if have curl; then
            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --no-modify-path
        else
            TMP_DIR="$(mktemp -d)"
            download "https://sh.rustup.rs" "$TMP_DIR/rustup.sh" || die "could not fetch rustup"
            sh "$TMP_DIR/rustup.sh" -y --no-modify-path
        fi
        # shellcheck disable=SC1091
        [ -f "$HOME/.cargo/env" ] && . "$HOME/.cargo/env"
        export PATH="$HOME/.cargo/bin:$PATH"
        hash -r 2>/dev/null || true
    fi
    have cargo || die "rust installed but cargo is not on PATH; open a new shell and re-run"

    local version
    version="$(cargo --version 2>/dev/null | awk '{print $2}')"
    if version_at_least "$version" "$MIN_RUST"; then
        ok "cargo ${version}"
    else
        warn "cargo ${version} is older than ${MIN_RUST}; updating"
        if have rustup; then
            rustup update stable >/dev/null 2>&1 || warn "rustup update failed; trying the build anyway"
        else
            warn "no rustup to update with; the build may fail on edition 2024"
        fi
    fi
}

need_system_deps() {
    if have apt-get; then
        pkg_install build-essential pkg-config libclang-dev
    elif have dnf; then
        pkg_install gcc gcc-c++ make pkgconf-pkg-config clang-devel
    elif have pacman; then
        pkg_install base-devel clang
    elif have zypper; then
        pkg_install gcc gcc-c++ make pkg-config clang-devel
    elif have apk; then
        pkg_install build-base pkgconf clang-dev
    elif have brew; then
        pkg_install llvm
    else
        warn "unknown package manager; ensure a C compiler and libclang are present"
        return 0
    fi
    ok "build toolchain and libclang present"
}

afl_version() {
    local banner="" first=""
    banner="$(afl-fuzz -h 2>&1 || true)"
    first="${banner%%$'\n'*}"
    printf '%s\n' "$first" | sed -E 's/.*afl-fuzz\+\+([0-9.]+[a-z]*).*/\1/'
}

need_afl() {
    if [ "$SKIP_AFL" = "1" ]; then
        warn "skipping AFL++ (--skip-afl); 'build', 'fuzz', 'corpus' and 'minimize' will not run"
        return 0
    fi
    if have afl-fuzz; then
        ok "AFL++ $(afl_version) already installed"
        return 0
    fi
    info "installing AFL++ (the fuzzer ${BINARY} drives)"
    local installed=1
    if   have apt-get; then pkg_try "afl++" && installed=0
    elif have dnf;     then pkg_try american-fuzzy-lop++ && installed=0
    elif have pacman;  then pkg_try afl++ && installed=0
    elif have apk;     then pkg_try afl++ && installed=0
    elif have brew;    then pkg_try afl-fuzz && installed=0
    fi

    if [ "$installed" -ne 0 ] || ! have afl-fuzz; then
        warn "no AFL++ package for this system"
        warn "build it from upstream (do NOT patch it — ${BINARY} is AGPL-3.0 and relies on AFL++ staying unmodified):"
        warn "    git clone https://github.com/AFLplusplus/AFLplusplus && cd AFLplusplus && make distrib && ${SUDO:-} make install"
        return 0
    fi

    local found
    found="$(afl_version)"
    ok "AFL++ ${found}"
    if ! version_at_least "$found" "$VERIFIED_AFL"; then
        warn "this AFL++ is older than ${VERIFIED_AFL}, which is the release ${BINARY} is tested against"
        warn "campaigns still run; for the verified toolchain build upstream AFL++ as above"
    fi
}

build_from_source() {
    info "building ${BINARY} (release, this takes a few minutes on a cold cache)"
    cargo install --path "crates/${BINARY}" --root "${INSTALL_DIR%/bin}" --force --quiet \
        || die "build failed"
    if have strip; then strip "${INSTALL_DIR}/${BINARY}" 2>/dev/null || true; fi
    ok "installed ${INSTALL_DIR}/${BINARY}"
}

wire_path() {
    case ":$PATH:" in *":$INSTALL_DIR:"*) ok "$INSTALL_DIR already on PATH"; export PATH="$INSTALL_DIR:$PATH"; return ;; esac
    local shell rc=""
    shell="$(basename "${SHELL:-bash}")"
    case "$shell" in
        zsh)  rc="$HOME/.zshrc" ;;
        fish) mkdir -p "$HOME/.config/fish/conf.d"
              printf 'fish_add_path %s\n' "$INSTALL_DIR" > "$HOME/.config/fish/conf.d/${BINARY}.fish"
              ok "added to fish conf.d" ;;
        bash) rc="$HOME/.bashrc"; [ -f "$rc" ] || rc="$HOME/.bash_profile" ;;
        *)    rc="$HOME/.profile" ;;
    esac
    if [ -n "$rc" ] && ! grep -q "$INSTALL_DIR" "$rc" 2>/dev/null; then
        printf '\nexport PATH="%s:$PATH"\n' "$INSTALL_DIR" >> "$rc"
        ok "added $INSTALL_DIR to PATH in $rc"
    fi
    export PATH="$INSTALL_DIR:$PATH"
}

main() {
    banner
    if have "$BINARY"; then info "existing install at $(command -v "$BINARY") — updating"; fi

    header "Dependencies"
    need_system_deps
    need_afl

    header "Building from source"
    REPO="$(resolve_repo)"
    cd "$REPO"
    need_toolchain
    build_from_source

    wire_path

    header "Verify"
    if have "$BINARY"; then
        ok "$BINARY -> $(command -v "$BINARY")"
        "$BINARY" --version 2>/dev/null || true
    else
        warn "installed to $INSTALL_DIR but not yet on PATH — open a new shell"
    fi

    printf '\n%s\n\n' "  ${GREEN}${BOLD}${BINARY} is ready.${RESET}" >&2
    cat >&2 <<FOOTER
  ${DIM}rank the parser entry points of a source tree:${RESET}
    ${CYAN}${BINARY} surface ./libpng${RESET}

  ${DIM}build a target under sanitizers, then fuzz it:${RESET}
    ${CYAN}${BINARY} build https://github.com/glennrp/libpng --work /tmp/lisdex${RESET}
    ${CYAN}${BINARY} fuzz --target <harness> --seeds <dir> --findings /tmp/out --db /tmp/lisdex.sqlite${RESET}

  ${DIM}watch it live, or open the local console:${RESET}
    ${CYAN}${BINARY} tui   --db /tmp/lisdex.sqlite --findings /tmp/out${RESET}
    ${CYAN}${BINARY} serve --db /tmp/lisdex.sqlite --findings /tmp/out${RESET}

  ${DIM}draft a coordinated-disclosure advisory for each distinct bug:${RESET}
    ${CYAN}${BINARY} advisory --db /tmp/lisdex.sqlite --campaign 1${RESET}

  ${DIM}docs: https://github.com/${REPO_OWNER}/${REPO_NAME}${RESET}
FOOTER
    return 0
}

main "$@" </dev/null