security-agent-linux

Local-first Linux host security agent + SOC-style dashboard — npm packaging wrapper.

npm install deploys a Python-based detection engine, a hardened Web UI, and three systemd services onto any Linux host. A valid license token is required to start the protection services.

Table of contents

1. Customer install
2. Install from tarball or URL (no registry)
3. Licensing
4. Commands reference
5. Publishing to npm (vendor)
6. Private registry publishing (vendor)
7. Vendor release checklist
8. Build and verify (developer)
9. Update existing deployments across hosts

1. Customer install

From the public npm registry

# Install the package globally
sudo npm install -g security-agent-linux

# Deploy agent on this host (license token required)
sudo security-agent install --license-token "<TOKEN>"

# Update an existing licensed host:
# npm install updates the package, then re-run install to apply changes
sudo npm install -g security-agent-linux@latest
sudo security-agent install

# Start all services
sudo security-agent start

# Print SSH tunnel command for Web UI access
security-agent tunnel

The install step:

• copies payload to /var/lib/security-agent/app
• creates /etc/security-agent/config.json
• creates and enables three hardened systemd units
• prompts for a Web UI password (minimum 10 characters)

Services only start if the license token passes Ed25519 verification against /etc/security-agent/license_pubkey.pem. Without a valid token the agent runs in detect-only mode (no quarantine, no firewall rules, no AI).

2. Install from tarball or URL (no registry)

Use this when the package has not been published to a registry yet, or when operating in an air-gapped environment.

# ── Option A: tarball copied to the server ────────────────────────────────
scp security-agent-linux-0.2.0.tgz user@server:/tmp/
ssh user@server
sudo npm install -g /tmp/security-agent-linux-0.2.0.tgz
sudo security-agent install --license-token "<TOKEN>"

# ── Option B: HTTPS URL (self-hosted download server) ────────────────────
sudo npm install -g "https://downloads.example.com/security-agent-linux-0.2.0.tgz"
sudo security-agent install --license-token "<TOKEN>"

# ── Option C: GitHub release asset URL ───────────────────────────────────
sudo npm install -g "https://github.com/your-org/security-agent/releases/download/v0.2.0/security-agent-linux-0.2.0.tgz"
sudo security-agent install --license-token "<TOKEN>"

3. Licensing

License tokens are Ed25519-signed JWS payloads bound to the machine's install_id.

First-time setup

# 1. Generate an install_id for this machine
sudo security-agent license request
# → prints { "install_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }
# Send this ID to your license server to mint a token.

# 2. Install the token on the machine
sudo security-agent install --license-token "<TOKEN>"
# or, after an existing install:
sudo security-agent license set --token "<TOKEN>"

# 3. Check license status
security-agent license status

How verification works

1. The vendor ships vendor_public_key.pem (Ed25519) inside the npm payload.
2. On first install, that key is written to /etc/security-agent/license_pubkey.pem.
3. Every install call verifies the token signature against this key and the machine's install_id. If verification fails, the agent and AI-worker services are not started.

Placing the public key manually

If you need to pre-provision the key before install:

sudo mkdir -p /etc/security-agent
sudo install -m 644 vendor_public_key.pem /etc/security-agent/license_pubkey.pem

4. Commands reference

security-agent install [--license-token <TOKEN>] [OPTIONS]
  --host <IP>          Web UI bind address  (default: 127.0.0.1)
  --port <PORT>        Web UI port          (default: 18789)
  --interval <SEC>     Scan interval        (default: 120)
  --max-files <N>      Max files per cycle  (default: 200)
  --detect-only        Never quarantine or block (override)
  --allow-unlicensed   VENDOR TESTING ONLY — bypasses license check

If /etc/security-agent/license.token already exists, security-agent install can be re-run during updates without passing the token (sudo security-agent install).

security-agent start | stop | restart | status
security-agent tunnel          — print SSH port-forward command
security-agent password        — re-run Web UI password setup
security-agent license request — print install_id
security-agent license set --token <TOKEN>
security-agent license status

Note: install, start, stop, restart, and license set require sudo.

5. Publishing to npm (vendor)

Prerequisites

• npm account with publish rights to the security-agent-linux package name
• Full repo checked out so prepare can bundle the payload
• vendor_public_key.pem present at the repo root (ships inside the package)

Steps

cd npm/security-agent

# 1. Authenticate with the public npm registry
npm login
# → enter username, password, OTP

# 2. (Optional) Dry-run to see what would be published
npm pack --dry-run

# 3. Run the integrity check (also runs automatically as prepublishOnly)
npm run verify-pack

# 4. Publish to the public registry
npm publish --access public

# 5. Confirm the published package
npm info security-agent-linux

After publish, customers install with:

sudo npm install -g security-agent-linux

6. Private registry publishing (vendor)

Use a private registry (Verdaccio, GitHub Packages, Artifactory, etc.) when you do not want the package publicly accessible.

# ── Point npm at your private registry ───────────────────────────────────
npm config set registry https://npm.your-company.com/

# Or scope it so only this package uses the private registry:
npm config set @your-scope:registry https://npm.your-company.com/

# ── Authenticate ──────────────────────────────────────────────────────────
npm login --registry https://npm.your-company.com/

# ── Publish ───────────────────────────────────────────────────────────────
npm publish --registry https://npm.your-company.com/

# ── Customer install from private registry ────────────────────────────────
sudo npm install -g security-agent-linux \
  --registry https://npm.your-company.com/

GitHub Packages example

# In package.json add: "publishConfig": { "registry": "https://npm.pkg.github.com" }
npm login --registry https://npm.pkg.github.com --scope @your-org
npm publish

7. Vendor release checklist

Follow these steps for every production release:

[ ] 1.  Bump version in package.json  (semver: patch / minor / major)
        npm version patch   # or minor / major
        # → updates package.json and creates a git tag

[ ] 2.  Ensure vendor_public_key.pem is present at the repo root.
        ls -l ../../vendor_public_key.pem

[ ] 3.  Run the pack integrity check (builds payload + verifies tarball).
        npm run verify-pack
        # Must print "ALL CHECKS PASSED" and show size < 5 MB.

[ ] 4.  Inspect the tarball contents manually.
        tar -tzf security-agent-linux-<VER>.tgz | sort

[ ] 5.  Test install from the local tarball on a clean VM.
        sudo npm install -g ./security-agent-linux-<VER>.tgz
        sudo security-agent install --license-token "<TEST_TOKEN>"
        security-agent license status

[ ] 6.  Publish to the registry.
        # Public:
        npm publish --access public
        # Private:
        npm publish --registry https://npm.your-company.com/

[ ] 7.  Verify the published package installs cleanly.
        sudo npm install -g security-agent-linux   # or private registry URL
        security-agent --help

[ ] 8.  Tag and push the release commit.
        git push origin main --tags

[ ] 9.  Attach the .tgz and its sha256 to the GitHub/GitLab release asset
        so customers can verify downloads out-of-band.
        sha256sum security-agent-linux-<VER>.tgz

8. Build and verify (developer)

Build the tarball

cd npm/security-agent

# Sync payload from repo and pack (no publish)
npm pack
# → security-agent-linux-<VER>.tgz

npm pack triggers scripts/sync_payload.js via the prepare hook. It copies:

| Source (repo root) | Destination in payload/ | |---------------------------|--------------------------| | security_v2/ | payload/security_v2/ | | ui_web/dist/ | payload/ui_web/dist/ | | security_cli_v2.py | payload/security_cli_v2.py | | config.template.json | payload/config.template.json | | vendor_public_key.pem | payload/vendor_public_key.pem (if present) |

The following are always excluded from the payload:

• __pycache__/, *.pyc, .pytest_cache/
• *.db, *.sqlite, *.sqlite3, *.db-journal, *.db-wal, *.db-shm
• logs/, *.log
• .env, .env.*

Verify tarball integrity (CI gate)

npm run verify-pack

This script (scripts/verify_pack.js):

1. Runs npm pack to a temporary directory.
2. Lists every entry in the .tgz.
3. Fails if any forbidden file pattern is present.
4. Fails if the tarball exceeds 5 MB.
5. Prints the tgz filename, sha256 digest, and size on success.

verify-pack also runs automatically as prepublishOnly, so npm publish will abort if the check fails.

Systemd services installed

| Service | Purpose | |----------------------------------|--------------------------------| | security-agent.service | Autonomous detection loop | | security-agent-web.service | Local Web UI (port 18789) | | security-agent-ai-worker.service | Isolated AI inference worker |

All units run as root with systemd hardening: NoNewPrivileges, PrivateTmp, ProtectHome, ProtectSystem=strict, MemoryDenyWriteExecute, RestrictAddressFamilies, and more.

Files on the host after install

/etc/security-agent/
  config.json              Main configuration (mode 0600)
  license.token            License token     (mode 0600)
  license_pubkey.pem       Vendor Ed25519 public key

/var/lib/security-agent/
  install_id               Machine UUID      (mode 0600)
  app/                     Deployed payload copy
  venv/                    Python virtualenv (psutil)
  quarantine/              Quarantined files

9. Update existing deployments across hosts

Use this helper when the package is already licensed and you only need to push an updated security-agent-linux build to one or more servers.

cd /root/ai_security_framework/npm/security-agent

# Update this host only (reads /etc/security-agent/license.token)
./scripts/update-security-agent.sh

# Update one remote host
./scripts/update-security-agent.sh --host 192.168.1.10 --user root

# Update multiple hosts, reusing the existing local token file and passing npm auth file
./scripts/update-security-agent.sh \
  --license-token-file /etc/security-agent/license.token \
  --npm-userconfig /tmp/npm-security-agent.npmrc \
  --host server-a --host server-b --host server-c

# Pin version if required
./scripts/update-security-agent.sh --version 0.3.1

If one remote host fails, the script stops by default. Add --continue-on-error to keep updating remaining hosts.