Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

17.0 KB
Raw Blame
#!/usr/bin/env bash
###############################################################################
# AiSOC — Preflight checks (Linux + macOS).
#
# This is a sourced library, not a standalone script. It's loaded by
# install.sh before any prerequisite work begins, and is also runnable on
# its own via:
#
#   bash scripts/install/preflight.sh
#
# Goal: catch the things that will make `pnpm aisoc:demo` fail four minutes
# from now — *before* we download a gigabyte of Docker images and ask the
# user to type their sudo password.
#
# We check, in order:
#
#   1. CPU architecture (must be amd64 or arm64)
#   2. Total RAM (≥ 4 GB hard fail, ≥ 8 GB recommended)
#   3. Free disk space at the install root and at $HOME/.docker
#      (≥ 10 GB hard fail, ≥ 20 GB recommended)
#   4. Internet reachability (DNS resolves + HTTPS to ghcr.io / github.com)
#   5. Required ports are free, OR already used by an AiSOC container we can
#      reuse — anything else is a conflict the user has to resolve
#   6. No leftover/conflicting AiSOC containers from a previous run that
#      would refuse to start cleanly
#   7. macOS-specific: Docker Desktop is installed *and* has at least 4 GB
#      RAM allocated to the VM (smaller and the api crashes mid-boot)
#
# Each check produces one line of output and one of three states:
#
#   PASS — silently records ok=$ok+1
#   WARN — prints a yellow line, increments warn count, but doesn't fail
#   FAIL — prints a red line, increments fail count
#
# At the end we print a summary. If any FAILs were recorded we exit 1
# *unless* the caller passed AISOC_PREFLIGHT_SOFT=1 (which install.sh sets
# when re-running preflight after a fix, so we don't bail twice).
#
# Exit codes (when run standalone):
#   0  all checks passed
#   1  at least one hard FAIL — installer would not succeed
#   2  preflight itself failed (couldn't gather data)
#
# Reads (no writes):
#   AISOC_PREFLIGHT_SOFT  if set to 1, return non-zero count instead of exit
#   AISOC_REPO_ROOT       if set, used as the install location for disk-space
#                         checks. Otherwise we use $PWD when sourced or
#                         $HOME/aisoc when run standalone.
#   AISOC_SKIP_NETWORK    if 1, skip the connectivity probes (for air-gapped
#                         testing — preflight will WARN, not FAIL).
###############################################################################

# Don't `set -e` because we need to inspect the exit code of each check and
# keep going. The caller (install.sh) sets it; we explicitly disable it on
# entry and restore it at the end so we don't surprise sourced callers.
_AISOC_PREFLIGHT_PREV_E="$(set +o | grep errexit)"
set +e

# ─── Config ──────────────────────────────────────────────────────────────────

# Hard floor / recommended floor for resources. Anything below the hard floor
# is a FAIL; anything between hard and recommended is a WARN. These numbers
# come from running the demo stack repeatedly and watching what actually
# breaks first when the system is starved (api OOM-kills around 3 GB total
# RAM, postgres + opensearch trash the disk below 8 GB free).
readonly _PF_RAM_MIN_MB=4096
readonly _PF_RAM_REC_MB=8192
readonly _PF_DISK_MIN_GB=10
readonly _PF_DISK_REC_GB=20

# Ports the demo stack exposes on the host. We probe each one and (a)
# tolerate it being free, (b) tolerate it being held by an aisoc-* container
# from a previous run, but (c) fail if it's held by anything else. The list
# is kept in lockstep with infra/compose/docker-compose.demo.yml — when a port is added
# there, add it here too.
#
# Using parallel arrays instead of an associative array because macOS still
# ships Bash 3.2 by default and `declare -A` only works in 4+.
readonly _PF_PORT_NUMS=(3000 5432 6379 8000 8001 8086 9092)
readonly _PF_PORT_NAMES=("web console" "postgres" "redis" "api" "agents" "realtime ws" "kafka")

# Hosts we curl during the connectivity probe. We hit specific endpoints
# that we know will return 200 (not just any path on the host), because
# ghcr.io's root replies 404 and would generate false negatives.
#
# - api.github.com/zen: a stable lightweight 200 endpoint, also confirms
#   github.com cert chain
# - ghcr.io/v2/: Docker Registry API root, returns 200 (or 401 with -f off)
# - registry.npmjs.org/: returns the registry status JSON, a 200
readonly _PF_NET_HOSTS=(
  "https://api.github.com/zen"
  "https://ghcr.io/v2/"
  "https://registry.npmjs.org/"
)

# ─── Logging (terminal-aware, mirrors install.sh) ────────────────────────────

if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
  _PF_RED=$'\033[31m'
  _PF_GREEN=$'\033[32m'
  _PF_YELLOW=$'\033[33m'
  _PF_BLUE=$'\033[34m'
  _PF_DIM=$'\033[2m'
  _PF_BOLD=$'\033[1m'
  _PF_RESET=$'\033[0m'
else
  _PF_RED=""; _PF_GREEN=""; _PF_YELLOW=""; _PF_BLUE=""; _PF_DIM=""; _PF_BOLD=""; _PF_RESET=""
fi

_PF_OK=0
_PF_WARN=0
_PF_FAIL=0
_PF_FAIL_HINTS=()

_pf_pass() {
  printf '  %s✓%s %s\n' "$_PF_GREEN" "$_PF_RESET" "$1"
  _PF_OK=$((_PF_OK + 1))
}

_pf_warn() {
  printf '  %s!%s %s\n' "$_PF_YELLOW" "$_PF_RESET" "$1"
  if [ -n "${2:-}" ]; then
    printf '    %shint:%s %s\n' "$_PF_DIM" "$_PF_RESET" "$2"
  fi
  _PF_WARN=$((_PF_WARN + 1))
}

_pf_fail() {
  printf '  %s✗%s %s\n' "$_PF_RED" "$_PF_RESET" "$1"
  if [ -n "${2:-}" ]; then
    printf '    %sfix:%s %s\n' "$_PF_DIM" "$_PF_RESET" "$2"
    _PF_FAIL_HINTS+=("$2")
  fi
  _PF_FAIL=$((_PF_FAIL + 1))
}

# ─── Helpers ─────────────────────────────────────────────────────────────────

_pf_have() { command -v "$1" >/dev/null 2>&1; }

# Print integer MB of RAM. Linux: parse /proc/meminfo. macOS: hw.memsize.
# Falls back to "0" if neither path works (treat as unknown — we'll WARN).
_pf_total_ram_mb() {
  if [ -r /proc/meminfo ]; then
    awk '/^MemTotal:/ { printf "%d\n", $2/1024; exit }' /proc/meminfo
  elif _pf_have sysctl; then
    # hw.memsize is bytes. Divide by 1024^2 for MB.
    sysctl -n hw.memsize 2>/dev/null | awk '{ printf "%d\n", $1/1024/1024 }'
  else
    echo 0
  fi
}

# Print integer GB of free space at the given path (rounded down). Uses
# `df -P -k` because BSD-df and GNU-df disagree on column order without -P.
_pf_free_disk_gb() {
  local path="$1"
  if [ ! -d "$path" ]; then
    # Walk up to the nearest existing parent — `df` won't report on a path
    # that doesn't exist yet, and we frequently pre-check dirs we're about
    # to create.
    while [ -n "$path" ] && [ "$path" != "/" ] && [ ! -d "$path" ]; do
      path="$(dirname "$path")"
    done
  fi
  df -P -k "$path" 2>/dev/null | awk 'NR==2 { printf "%d\n", $4/1024/1024 }'
}

# Returns 0 if a TCP listener is already bound to localhost:$1, else 1.
# We try `lsof` first (universal), `ss` second (modern Linux), then a raw
# /dev/tcp probe as a last-resort. /dev/tcp is bash-only and may be disabled
# on hardened distros, hence the cascade.
_pf_port_listener() {
  local port="$1"
  if _pf_have lsof; then
    lsof -nP -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1 && return 0
    return 1
  fi
  if _pf_have ss; then
    ss -lnt "sport = :$port" 2>/dev/null | grep -q "LISTEN" && return 0
    return 1
  fi
  if (echo > "/dev/tcp/127.0.0.1/$port") >/dev/null 2>&1; then
    return 0
  fi
  return 1
}

# Print the friendly label of whatever process is holding $1, or "" if we
# can't tell. Examples: "docker (aisoc-api-1)", "postgres (system)", "node".
_pf_port_owner() {
  local port="$1" pid cmd container
  if _pf_have lsof; then
    pid="$(lsof -nP -iTCP:"$port" -sTCP:LISTEN -t 2>/dev/null | head -n1)"
    if [ -n "$pid" ]; then
      cmd="$(ps -p "$pid" -o comm= 2>/dev/null | tr -d '[:space:]')"
      if [ "$cmd" = "com.docker.backend" ] || [ "$cmd" = "com.docker.vmnetd" ] || [ "$cmd" = "docker-pr" ] || [ "$cmd" = "docker-proxy" ]; then
        # Try to find the container that opened this published port.
        if _pf_have docker; then
          container="$(docker ps --filter "publish=$port" --format '{{.Names}}' 2>/dev/null | head -n1)"
          if [ -n "$container" ]; then
            echo "docker container: $container"
            return 0
          fi
        fi
        echo "docker (unknown container)"
        return 0
      fi
      echo "${cmd:-pid $pid}"
      return 0
    fi
  fi
  echo ""
}

# Returns 0 if the given port-owner string indicates an AiSOC container —
# i.e. a previous demo run we can safely reuse / restart. The names come
# from infra/compose/docker-compose.demo.yml + the project's compose project name
# (defaults to the directory name, usually "aisoc").
#
# We can't use ${var,,} (bash 4+) here because macOS still ships bash 3.2
# by default. Pipe through tr instead — works everywhere.
_pf_owner_is_aisoc() {
  local lc
  lc="$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')"
  case "$lc" in
    *aisoc*) return 0 ;;
    *) return 1 ;;
  esac
}

# ─── Checks ──────────────────────────────────────────────────────────────────

_pf_check_arch() {
  case "$(uname -m)" in
    x86_64|amd64|aarch64|arm64)
      _pf_pass "CPU architecture: $(uname -m)"
      ;;
    armv7*|armv6*|i?86)
      _pf_fail "CPU architecture $(uname -m) is not supported." \
        "AiSOC images are amd64 + arm64 only. 32-bit ARM and i386 won't work."
      ;;
    *)
      _pf_warn "CPU architecture $(uname -m) is unrecognised — proceed at your own risk."
      ;;
  esac
}

_pf_check_ram() {
  local mb
  mb="$(_pf_total_ram_mb)"
  if [ "$mb" = "0" ] || [ -z "$mb" ]; then
    _pf_warn "Couldn't read total system RAM."
    return
  fi
  if [ "$mb" -lt "$_PF_RAM_MIN_MB" ]; then
    _pf_fail "RAM: ${mb} MB total (need ≥ ${_PF_RAM_MIN_MB} MB)." \
      "Add memory or run on a larger machine. The demo stack needs ~3 GB resident."
  elif [ "$mb" -lt "$_PF_RAM_REC_MB" ]; then
    _pf_warn "RAM: ${mb} MB total (recommended ≥ ${_PF_RAM_REC_MB} MB)." \
      "Demo will run but may swap. 8 GB is the sweet spot."
  else
    _pf_pass "RAM: ${mb} MB total"
  fi
}

_pf_check_disk() {
  local install_root="${AISOC_REPO_ROOT:-${PWD:-/}}"
  local install_gb
  install_gb="$(_pf_free_disk_gb "$install_root")"
  if [ -z "$install_gb" ]; then install_gb=0; fi

  if [ "$install_gb" -lt "$_PF_DISK_MIN_GB" ]; then
    _pf_fail "Disk: only ${install_gb} GB free at $install_root (need ≥ ${_PF_DISK_MIN_GB} GB)." \
      "Free up space or pass --clone-dir to point install.sh at a roomier disk."
  elif [ "$install_gb" -lt "$_PF_DISK_REC_GB" ]; then
    _pf_warn "Disk: ${install_gb} GB free at $install_root (recommended ≥ ${_PF_DISK_REC_GB} GB)."
  else
    _pf_pass "Disk: ${install_gb} GB free at $install_root"
  fi

  # Docker writes its image cache to /var/lib/docker on Linux and to
  # ~/Library/Containers/com.docker.docker on macOS. Probe whichever one
  # exists. We need this because /home and /var are often separate
  # filesystems and a "20 GB free in $HOME" check tells us nothing about
  # whether a 4 GB image pull will succeed.
  local docker_root=""
  if [ -d /var/lib/docker ]; then
    docker_root=/var/lib/docker
  elif [ -d "$HOME/Library/Containers/com.docker.docker" ]; then
    docker_root="$HOME/Library/Containers/com.docker.docker"
  fi
  if [ -n "$docker_root" ]; then
    local d_gb
    d_gb="$(_pf_free_disk_gb "$docker_root")"
    if [ -n "$d_gb" ] && [ "$d_gb" -lt "$_PF_DISK_MIN_GB" ]; then
      _pf_fail "Disk: only ${d_gb} GB free at Docker root ($docker_root)." \
        "Run 'docker system prune -af' to reclaim space, or move the Docker root."
    fi
  fi
}

_pf_check_network() {
  if [ "${AISOC_SKIP_NETWORK:-0}" = "1" ]; then
    _pf_warn "Skipping network checks (AISOC_SKIP_NETWORK=1)."
    return
  fi
  if ! _pf_have curl; then
    _pf_warn "curl not installed — skipping connectivity probe (will install in step 1)."
    return
  fi
  local host failed=0 http_code
  for host in "${_PF_NET_HOSTS[@]}"; do
    # -m 6: hard 6 s timeout per host. -s: silent. -L: follow redirects.
    # -o /dev/null: discard body. -w '%{http_code}': print just the status.
    # We treat anything in 2xx/3xx/401 as "host is up" — 401 is GHCR's
    # legitimate "auth required" response, not a connectivity failure.
    http_code="$(curl -s -L -m 6 -o /dev/null -w '%{http_code}' "$host" 2>/dev/null || echo "000")"
    case "$http_code" in
      2*|3*|401|403) continue ;;
      *)
        _pf_warn "Couldn't reach $host (HTTP ${http_code:-no-response})." \
          "If you're behind a corporate proxy, set https_proxy + http_proxy before continuing."
        failed=$((failed + 1))
        ;;
    esac
  done
  if [ "$failed" -eq 0 ]; then
    _pf_pass "Network: github.com, ghcr.io, npmjs.org all reachable"
  fi
}

_pf_check_ports() {
  local i port name owner conflicts=0 reused=0
  for i in "${!_PF_PORT_NUMS[@]}"; do
    port="${_PF_PORT_NUMS[$i]}"
    name="${_PF_PORT_NAMES[$i]}"
    if ! _pf_port_listener "$port"; then
      continue
    fi
    owner="$(_pf_port_owner "$port")"
    if _pf_owner_is_aisoc "$owner"; then
      _pf_warn "Port $port ($name) is held by an existing AiSOC container ($owner)." \
        "We'll reuse it — but if a previous demo crashed, run 'pnpm aisoc:demo:down' first."
      reused=$((reused + 1))
    else
      _pf_fail "Port $port ($name) is in use by ${owner:-an unknown process}." \
        "Stop that process, or set the corresponding *_PORT env var to remap. See docs/QUICK_INSTALL.md#port-conflicts."
      conflicts=$((conflicts + 1))
    fi
  done
  if [ "$conflicts" -eq 0 ] && [ "$reused" -eq 0 ]; then
    _pf_pass "All required ports (${_PF_PORT_NUMS[*]}) are free"
  fi
}

_pf_check_stale_containers() {
  if ! _pf_have docker; then
    return
  fi
  if ! docker info >/dev/null 2>&1; then
    return
  fi
  # Look for stopped/exited aisoc-* containers from a previous failed run.
  # `docker compose up` will sometimes refuse to recreate these depending on
  # the volume state, so we surface them up-front.
  local stale
  stale="$(docker ps -a --filter "name=aisoc-" --filter "status=exited" --format '{{.Names}}' 2>/dev/null | head -5)"
  if [ -n "$stale" ]; then
    _pf_warn "Stale AiSOC containers from a previous run:" \
      "Run 'pnpm aisoc:demo:down' (in the AiSOC clone) to clear them. Listed: $(echo "$stale" | tr '\n' ' ')"
  fi
}

_pf_check_macos_docker() {
  if [ "$(uname -s)" != "Darwin" ]; then return; fi
  if ! _pf_have docker; then return; fi
  # If docker CLI is installed but the daemon isn't reachable, say so
  # *clearly* — we previously printed "Docker Desktop is allocated 0 MB"
  # which sounded like a config problem when actually Docker Desktop just
  # wasn't running. install.sh will boot it on macOS, but the user needs
  # to know that's what's happening.
  if ! docker info >/dev/null 2>&1; then
    _pf_warn "Docker Desktop appears installed but the daemon isn't running." \
      "install.sh will launch it; or open Docker.app yourself and re-run."
    return
  fi
  # Daemon is up — verify it has enough RAM allocated.
  local raw mb
  raw="$(docker info --format '{{json .MemTotal}}' 2>/dev/null)"
  if [ -z "$raw" ] || [ "$raw" = "null" ] || [ "$raw" = "0" ]; then
    # Daemon answered but couldn't tell us its memory budget — odd, skip.
    return
  fi
  # MemTotal is bytes.
  mb=$((raw / 1024 / 1024))
  if [ "$mb" -lt 4000 ]; then
    _pf_fail "Docker Desktop is allocated only ${mb} MB of RAM (need ≥ 4096 MB)." \
      "Open Docker Desktop → Settings → Resources → Memory and bump to at least 4 GB."
  fi
}

# ─── Driver ──────────────────────────────────────────────────────────────────

run_aisoc_preflight() {
  printf '\n%s%sPreflight checks%s\n' "$_PF_BOLD" "$_PF_BLUE" "$_PF_RESET"

  _pf_check_arch
  _pf_check_ram
  _pf_check_disk
  _pf_check_network
  _pf_check_ports
  _pf_check_stale_containers
  _pf_check_macos_docker

  printf '\n  %sSummary:%s %s%d passed%s, %s%d warnings%s, %s%d failures%s\n\n' \
    "$_PF_BOLD" "$_PF_RESET" \
    "$_PF_GREEN" "$_PF_OK" "$_PF_RESET" \
    "$_PF_YELLOW" "$_PF_WARN" "$_PF_RESET" \
    "$_PF_RED" "$_PF_FAIL" "$_PF_RESET"

  if [ "$_PF_FAIL" -gt 0 ]; then
    printf '%s%sPreflight FAILED.%s Address the items above and re-run.\n' \
      "$_PF_BOLD" "$_PF_RED" "$_PF_RESET"
    printf '%sFull troubleshooting:%s docs/QUICK_INSTALL.md#troubleshooting\n\n' \
      "$_PF_DIM" "$_PF_RESET"
    if [ "${AISOC_PREFLIGHT_SOFT:-0}" = "1" ]; then
      return 1
    fi
    exit 1
  fi
  return 0
}

# Run automatically only when invoked as a script, not when sourced.
# BASH_SOURCE[0] == $0 means "called directly".
if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
  run_aisoc_preflight
  rc=$?
  # Restore the caller's errexit setting before returning.
  eval "$_AISOC_PREFLIGHT_PREV_E"
  exit $rc
fi

# Sourced — restore errexit and let the caller decide when to run.
eval "$_AISOC_PREFLIGHT_PREV_E"