AssemblyLine 4 Server

MCP server for the AssemblyLine 4 malware analysis platform.

Setup

npm install
npm run build

Copy .env.example to .env and fill in your credentials:

AL4_URL=https://your-al4-instance:443
AL4_USERNAME=your_username
AL4_APIKEY=keyname:your_api_key_password

API keys are created in AssemblyLine under Account → Security → Manage API Keys.

Running

AL4_URL=... AL4_USERNAME=... AL4_APIKEY=... node dist/src/index.js

Claude Code integration

Add to your ~/.claude/claude_desktop_config.json (or project .claude/settings.json):

{
  "mcpServers": {
    "assemblyline4": {
      "command": "node",
      "args": ["/absolute/path/to/vibe-assemblylinev4-mcp/dist/src/index.js"],
      "env": {
        "AL4_URL": "https://your-al4-instance:443",
        "AL4_USERNAME": "your_username",
        "AL4_APIKEY": "keyname:password"
      }
    }
  }
}

Self-signed / dev certificates

Set AL4_TLS_VERIFY=false in the env block to skip TLS verification.

Available tools

Tool	Description
al4_whoami	Current authenticated user
al4_submit_file	Sync file submission (path on disk)
al4_submit_url	Sync URL submission
al4_submit_sha256	Sync submission by hash (file must exist in AL4 store)
al4_ingest_file	Async file ingestion with optional notification queue
al4_ingest_url	Async URL ingestion
al4_ingest_sha256	Async hash ingestion
al4_submission_is_complete	Poll whether a submission has finished
al4_submission_get	Submission metadata
al4_submission_full	Complete results tree
al4_submission_summary	Summarised results
al4_ingest_get_messages	Drain a notification queue
al4_search_submissions	Lucene search over submissions
al4_search_alerts	Lucene search over alerts
al4_search_files	Lucene search over the file store
al4_search_results	Lucene search over service results
al4_alert_get	Fetch a single alert by ID
al4_file_info	File metadata by SHA256
al4_file_results	All service results for a file
al4_file_score	Highest score for a file

Testing & CI

Two layers of tests live under test/:

• test/integration.ts — drives AL4Client and the MCP server end-to-end against an in-process mock of the AL4 REST API (test/mock-al4.ts). Fast, hermetic, runs on every push/PR via .github/workflows/ci.yml.

  npm test
  

• test/e2e.ts — drives AL4Client against a real Assemblyline 4 appliance. The .github/workflows/e2e.yml workflow spins up the upstream assemblyline-docker-compose appliance (core stack only — Elasticsearch, Redis, MinIO, AL core/UI/nginx; service images are skipped to fit the runner's disk quota), bootstraps the admin user, mints an API key, and runs the suite. Because submissions are not blocked on services, they complete with an empty result tree — enough to validate every API the MCP server exposes.

  The e2e workflow runs:

  • nightly (05:27 UTC),
  • on workflow_dispatch,
  • on PRs labelled run-e2e.

  To reproduce locally:

  bash scripts/ci/start-al4.sh
  APIKEY=$(AL4_URL=https://localhost AL4_ADMIN_USER=admin AL4_ADMIN_PASSWORD=admin \
           bash scripts/ci/create-apikey.sh)
  AL4_URL=https://localhost AL4_USERNAME=admin AL4_APIKEY=$APIKEY \
    AL4_TLS_VERIFY=false node dist/test/e2e.js
  

Running CI locally

Two equivalent paths, depending on what you want to validate:

1. The fast workflow, exactly as GitHub Actions runs it — via act:

   # one-time: install act (https://nektosact.com/installation/)
   npm run ci:local            # runs .github/workflows/ci.yml in Docker
   

   act reads .actrc, which pins the catthehacker ubuntu:act-latest image (has Node, git, curl, etc.). This is the cleanest way to catch regressions in the workflow YAML itself.

2. The e2e workflow — act is not recommended here because the job spins up its own docker-compose stack, and docker-in-docker via act makes networking and disk usage painful. Use the wrapper script instead, which runs the same steps directly on your host:

   npm run e2e:local           # build → start appliance → mint key → run e2e → teardown
   KEEP_RUNNING=1 npm run e2e:local   # leave appliance up afterwards for poking
   SKIP_BUILD=1   npm run e2e:local   # skip npm ci + tsc, reuse dist/
   

   Or break it apart:

   npm run e2e:up              # just bring up the appliance
   APIKEY=$(npm run --silent e2e:apikey)
   AL4_URL=https://localhost AL4_USERNAME=admin AL4_APIKEY=$APIKEY \
     AL4_TLS_VERIFY=false npm run test:e2e
   

   Requirements: Linux host (or WSL2 / macOS), docker + compose plugin, node 20+, ~15 GB free disk. Windows users: run the scripts from inside WSL — the appliance won't come up under Git Bash because of how docker-compose paths and openssl interact on native Windows.