aegis-rex 1.5.1

package/README.md

@@ -0,0 +1,151 @@
+# aegis-rex
+
+**ÆGIS Security Audit (`rex`)** — a local, offline security auditor you can drive
+by hand *or* by an AI agent. No server, no telemetry, no account.
+
+This npm package is a **distribution channel and a cross-platform launcher**. The
+auditor itself is a single dependency-free Python file; there is no JavaScript
+dependency tree to audit, by design. A security tool that pulls transitive
+packages into your `PATH` is a supply-chain liability.
+
+```console
+$ npm i -g aegis-rex
+$ rex --audit
+```
+
+---
+
+## What it does
+
+`rex` runs **16 audit sections** (+ optional ClamAV = 17 checks) against the
+local machine and reports findings with severities:
+
+| | |
+|---|---|
+| System | system info, CPU & memory, disk, network, running processes |
+| Exposure | open ports, firewall, listening services |
+| Access | SSH config, sudo privileges, users & groups, SUID/SGID files |
+| Hygiene | world-writable files, sensitive file permissions, environment secrets, scheduled tasks, startup services |
+| Malware | ClamAV virus scan (only if ClamAV is installed) |
+
+Then it can ask an LLM for a remediation and apply it — with the commands
+classified for danger first. **Nothing is ever executed without `--apply`.**
+
+## Requirements
+
+| | |
+|---|---|
+| Python | **3.10+** (required — `rex.py` uses PEP 604 `X \| None` syntax evaluated at import) |
+| Node.js | 16+, only for this launcher |
+| `psutil` | *optional* — without it, 4 of 16 sections report `status: error` (see below) |
+| PyQt6 | *optional* — desktop GUI only (`rex --gui`); the CLI never needs it |
+| Display | *not* required for any `--` command |
+
+The launcher probes `python3`, `python`, and (on Windows) `py -3`, then hands over
+stdio and the exit code untouched. Install Python if it is missing:
+
+```console
+$ sudo apt install python3     # Debian/Ubuntu
+$ sudo dnf install python3     # Fedora/RHEL
+$ brew install python@3.12     # macOS
+$ winget install Python.Python.3.12   # Windows
+```
+
+Optional extras:
+
+```console
+$ pip install psutil           # 4 richer audit sections
+$ pip install psutil PyQt6     # + the desktop GUI
+```
+
+## Use as a human
+
+```console
+$ rex --audit                  # colour terminal report
+$ rex --audit --json           # machine-readable (aegis.rex.audit/1)
+$ rex --list-checks            # the 17 stable section ids
+$ rex --fix ssh-config --provider deepseek --json   # ask a model for the fix
+$ rex --gui                    # desktop window (needs PyQt6)
+```
+
+## Use from an agent
+
+This is the part the CLI is built around. Start with `--capabilities`: it prints
+the whole contract as JSON, so an agent can discover the surface instead of
+scraping `--help`.
+
+```console
+$ rex --capabilities           # full contract: commands, args, schemas, exit codes
+$ rex --rex-env                # launcher introspection: which python, where rex.py is
+```
+
+```console
+$ rex --audit --json --fail-on warn
+```
+
+### Exit codes
+
+Uniform across commands, so a wrapper can branch on them:
+
+| Code | Meaning |
+|---|---|
+| `0` | clean — audit ran, nothing met the `--fail-on` threshold |
+| `1` | audit ran and findings met the **explicit** `--fail-on` threshold |
+| `2` | bad arguments or unreadable input |
+| `3` | AI provider unreachable, unauthorized, or out of budget |
+| `4` | `--apply` ran and at least one command failed |
+
+`--fail-on` defaults to `none`, so `--audit` exits `0` unless you explicitly opt
+into gating. **CI must pass `--fail-on warn`** (or `critical`) to fail on findings.
+
+### Schemas
+
+| Command | Schema |
+|---|---|
+| `--audit --json` | `aegis.rex.audit/1` |
+| `--fix … --json` | `aegis.rex.fix/1` |
+| `--capabilities` | `aegis.rex.capabilities/1` |
+
+`summary.unassessed` lists section ids that could not be evaluated — currently the
+four `psutil` sections on a bare interpreter. They report `status: error`, which
+means *absence of evidence, not a pass*: a low score caused by a missing module
+stays distinguishable from a genuinely unhealthy host.
+
+### Redaction and safety
+
+Three sections — **Sudo / Privileges**, **SSH Config**, **Users & Groups** — are
+redacted in saved reports, because they leak usernames and host details. A report
+that mentions them is not consent to send them to a model, so `--fix` **refuses**
+to run from a saved report for those sections (exit `2`) unless you pass `--yes`.
+
+Every command a model proposes is classified before it is shown or run. Blocked
+patterns include `rm -rf /`, `dd … of=/dev/*`, `mkfs`, fork bombs,
+`curl … | sh`, and writes to `/etc/passwd`, `/etc/shadow`, `/etc/sudoers` and
+`/etc/hosts`. The same classifier backs both `--apply` and the GUI dialog, so
+they cannot disagree.
+
+### Providers
+
+| Provider | Notes |
+|---|---|
+| Ollama | local, private, can auto-pull the model; no API key |
+| Claude | `ANTHROPIC_API_KEY` |
+| DeepSeek | `DEEPSEEK_API_KEY` |
+
+Set the key in the environment, or configure it once in the GUI (stored in
+`~/.aegis_config.json`, mode `600`).
+
+## Artifact integrity
+
+`vendor/rex.py` is byte-identical to the source of truth published at
+<https://github.com/aegisinfo/rex> and served for direct download at
+<https://aegiscloud.org/rex>. `npm run sync` refreshes it under a version guard
+and refuses to proceed if `package.json` and the artifact disagree.
+
+```console
+$ sha256sum vendor/rex.py
+```
+
+## License
+
+MIT

package/bin/rex.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Cross-platform launcher for rex.py.
+ *
+ * rex is a Python security auditor. npm is only the distribution channel: this
+ * shim finds a suitable interpreter, then hands over stdio and the exit code
+ * untouched, so `rex --audit --json` behaves identically whether it is invoked
+ * from npm, from a shell alias, or by an AI agent reading --capabilities.
+ *
+ * No npm dependencies, by design. A security tool that pulls a dependency tree
+ * into your PATH is a supply-chain liability, and the launcher is small enough
+ * that it does not need one.
+ */
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const REX_PY = path.join(__dirname, '..', 'vendor', 'rex.py');
+const MIN_PYTHON = [3, 10];
+
+// GUI needs PyQt6; the headless audit/CLI path needs nothing but the stdlib.
+const GUI_ARGS = new Set(['--gui']);
+
+function fail(message, hint) {
+  process.stderr.write(`rex: ${message}\n`);
+  if (hint) process.stderr.write(`${hint}\n`);
+  process.exit(2);
+}
+
+/**
+ * Interpreters to try, in order of preference for the current platform.
+ * `py -3` is the supported launcher on Windows; bare `python` there is often
+ * the Microsoft Store stub, which we detect by probing it rather than trusting
+ * the name.
+ */
+function candidates() {
+  if (process.platform === 'win32') {
+    return [
+      { cmd: 'py', args: ['-3'] },
+      { cmd: 'python3', args: [] },
+      { cmd: 'python', args: [] },
+    ];
+  }
+  return [
+    { cmd: 'python3', args: [] },
+    { cmd: 'python', args: [] },
+  ];
+}
+
+/** Probe one candidate. Returns {ok, version, major, minor} without throwing. */
+function probe(candidate) {
+  const res = spawnSync(
+    candidate.cmd,
+    [...candidate.args, '-c',
+     'import sys;print("%d.%d.%d"%sys.version_info[:3])'],
+    { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+  );
+  if (res.error || res.status !== 0) return { ok: false };
+  const version = String(res.stdout || '').trim();
+  const parts = version.split('.').map((n) => parseInt(n, 10));
+  if (parts.length < 2 || Number.isNaN(parts[0]) || Number.isNaN(parts[1])) {
+    return { ok: false };
+  }
+  return { ok: true, version, major: parts[0], minor: parts[1] };
+}
+
+function tooOld(found) {
+  return (
+    found.major < MIN_PYTHON[0] ||
+    (found.major === MIN_PYTHON[0] && found.minor < MIN_PYTHON[1])
+  );
+}
+
+/** Resolve a usable interpreter, or exit with an actionable message. */
+function findPython() {
+  const tried = [];
+  let sawOld = null;
+
+  for (const candidate of candidates()) {
+    const found = probe(candidate);
+    if (!found.ok) {
+      tried.push(candidate.cmd);
+      continue;
+    }
+    if (tooOld(found)) {
+      if (!sawOld) sawOld = { cmd: candidate.cmd, ...found };
+      tried.push(`${candidate.cmd} (${found.version})`);
+      continue;
+    }
+    return candidate;
+  }
+
+  if (sawOld) {
+    fail(
+      `found Python ${sawOld.version} at '${sawOld.cmd}', but rex needs ` +
+        `${MIN_PYTHON.join('.')}+ (PEP 604 type syntax is evaluated at import).`,
+      installHint()
+    );
+  }
+  fail(
+    `no Python ${MIN_PYTHON.join('.')}+ interpreter found (tried: ${tried.join(', ') || 'none'}).`,
+    installHint()
+  );
+}
+
+function installHint() {
+  const lines = ['Install Python ' + MIN_PYTHON.join('.') + '+:'];
+  if (process.platform === 'win32') {
+    lines.push('  winget install Python.Python.3.12');
+    lines.push('  (or https://python.org/downloads — tick "Add python.exe to PATH")');
+  } else if (process.platform === 'darwin') {
+    lines.push('  brew install python@3.12');
+  } else {
+    lines.push('  sudo apt install python3   # Debian/Ubuntu');
+    lines.push('  sudo dnf install python3   # Fedora/RHEL');
+  }
+  lines.push('');
+  lines.push('Optional extras:');
+  lines.push('  pip install psutil            # 4 richer audit sections');
+  lines.push('  pip install psutil PyQt6      # + the desktop GUI');
+  return lines.join('\n');
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+
+  // Environment introspection, so an agent can tell "rex is broken" apart from
+  // "rex has no interpreter" without guessing.
+  if (argv.includes('--rex-env')) {
+    const python = findPython();
+    const found = probe(python);
+    process.stdout.write(
+      JSON.stringify(
+        {
+          launcher: 'aegis-rex',
+          platform: process.platform,
+          arch: process.arch,
+          node: process.version,
+          python: {
+            command: python.cmd,
+            args: python.args,
+            version: found.version,
+          },
+          rex_py: REX_PY,
+          rex_py_present: fs.existsSync(REX_PY),
+        },
+        null,
+        2
+      ) + '\n'
+    );
+    return 0;
+  }
+
+  if (!fs.existsSync(REX_PY)) {
+    fail(`bundled artifact missing at ${REX_PY} — reinstall: npm i -g aegis-rex`);
+  }
+
+  const python = findPython();
+  const wantsGui = argv.some((a) => GUI_ARGS.has(a));
+
+  const res = spawnSync(
+    python.cmd,
+    [...python.args, REX_PY, ...argv],
+    { stdio: 'inherit' }
+  );
+
+  if (res.error) {
+    fail(`failed to start ${python.cmd}: ${res.error.message}`);
+  }
+  if (res.signal) {
+    // Mirror the shell convention so `kill -TERM` on the GUI is observable.
+    process.kill(process.pid, res.signal);
+    return 128;
+  }
+
+  const code = res.status === null ? 1 : res.status;
+
+  // rex exit 2 is "usage / missing dependency". When the GUI was requested and
+  // PyQt6 is the reason, the raw Python traceback is not the useful message.
+  if (code === 2 && wantsGui) {
+    process.stderr.write(
+      '\nThe GUI needs PyQt6 (the audit and CLI do not):\n' +
+        `  ${python.cmd} -m pip install PyQt6\n` +
+        'Or run headless: rex --audit\n'
+    );
+  }
+  return code;
+}
+
+process.exit(main());

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "aegis-rex",
+  "version": "1.5.1",
+  "description": "Headless-drivable security auditor for Linux, macOS and Windows. Runs a 17-check local audit and can be driven by an AI agent (--capabilities / --audit --json / --fix). npm is the distribution channel; the tool itself is dependency-free Python.",
+  "bin": {
+    "rex": "bin/rex.js"
+  },
+  "files": [
+    "bin/rex.js",
+    "vendor/rex.py",
+    "vendor/LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "os": [
+    "linux",
+    "darwin",
+    "win32"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "sync": "node scripts/sync-artifact.js"
+  },
+  "keywords": [
+    "security",
+    "audit",
+    "hardening",
+    "cis",
+    "ssh",
+    "firewall",
+    "suid",
+    "secrets",
+    "ai-agent",
+    "llm",
+    "mcp",
+    "cli",
+    "headless",
+    "devsecops"
+  ],
+  "author": "AEGIS",
+  "license": "MIT",
+  "homepage": "https://aegiscloud.org/rex",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aegisinfo/rex.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aegisinfo/rex/issues"
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/vendor/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niklas Borneklint
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.