@bergabruh/system-scanner 0.1.0

package/LICENSE

@@ -0,0 +1,6 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+This plugin is distributed under the Apache License 2.0. The complete license
+is available at https://www.apache.org/licenses/LICENSE-2.0.

package/README.md

@@ -0,0 +1,185 @@
+# Mnogovid System Scanner
+
+Mnogovid System Scanner is a consent-gated Linux host assessment plugin. It
+orchestrates installed local tools and records redacted evidence; it never
+installs software, applies a fix, deletes/quarantines a file, saves PCAPs, or
+runs shell text.
+
+It is intentionally layered. No tool can prove a Linux host is clean: a
+rootkit can hide from user-space checks, package CVE state can differ because
+of distribution backports, and encrypted or unobserved traffic cannot be fully
+inspected.
+
+## Coverage
+
+| Area | Allowlisted adapters |
+| --- | --- |
+| Hardening | Lynis |
+| Malware / rootkits | ClamAV, rkhunter, chkrootkit |
+| File/package integrity | AIDE, `rpm -Va` |
+| Installed-package CVEs | debsecan |
+| Runtime inventory | osquery |
+| Listener and firewall exposure | `ss`, nftables |
+| Persistence | enabled systemd units and timers |
+| Audit, kernel, and logs | audit rules, loaded kernel modules, warning journal entries |
+| Containers | Docker and Podman inventory when their CLI is available |
+| Docker hardening and image CVEs | Docker security options/container posture, Trivy, Grype, Dockle |
+| Service posture | Nginx syntax; bounded local MySQL, PostgreSQL, Redis, MongoDB, and ClickHouse probes |
+| Active ports (explicit target only) | Nmap, top 100 ports with light version detection |
+| Live traffic metadata (bounded) | TShark, 5–300 seconds, no packet file |
+
+Missing executables are recorded as coverage gaps. The plugin does not attempt
+to install them or elevate privilege. Some checks need root access and will
+report failure rather than invoke `sudo`.
+
+## Run
+
+Install it from the Mnogovid marketplace, then use one of the native Codex
+commands:
+
+```text
+@mnogovid-system-scanner
+/mnogovid-system-scanner:system-scan
+```
+
+The `@` mention invokes the plugin onboarding prompt. The unified command first
+asks whether to assess the local host or a configured remote MCP host, checks
+the profile and toolchain, and creates a missing profile only after consent.
+On later runs it validates the existing profile and available adapters before
+asking which mode to use: adapters only, adapters plus AI triage, or adapters
+plus AI triage and independent review. It collects all scanner permissions
+separately.
+
+### Remote server over SSH-stdio MCP
+
+Install the same plugin on the remote host, preferably at
+`/opt/mnogovid-system-scanner`, and define an SSH alias for a dedicated audit
+account. Generate a static local Codex configuration stanza:
+
+```bash
+python3 /path/to/mnogovid-system-scanner/scripts/remote_mcp_config.py prod-audit
+```
+
+Copy its output into local `~/.codex/config.toml`, restart Codex, then use:
+
+```text
+/mnogovid-system-scanner:system-scan
+```
+
+The MCP protocol stays inside SSH stdio: no remote TCP listener or secret is
+required in the generated configuration. It explicitly disables SSH agent and
+other forwarding, enables batch mode, and requires a known host key. The utility
+only renders TOML; it does not edit the local configuration or contact the
+host. See [`remote-mcp.toml.example`](remote-mcp.toml.example).
+
+The unified command asks in chat which configured remote MCP connection to use
+when there is more than one, then asks a separate first consent before it
+connects or starts discovery. It defaults reports to the remote MCP process's
+current working directory and shows its resolved path before scanner planning.
+
+### Claude Code
+
+Install the plugin from the configured marketplace, start Claude in the
+selected report directory, then invoke:
+
+```text
+/system-scan
+```
+
+### OpenCode
+
+Add the package name to the project or global `opencode.json` and restart
+OpenCode:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@bergabruh/system-scanner"]
+}
+```
+
+OpenCode installs the package through Bun. The package starts its bundled,
+dependency-free Python scanner bridge itself; no `cwd`, MCP block, or copied
+`.opencode` assets are needed. Ask OpenCode to assess the local Linux host; it
+receives the `mnogovid_system_scanner` tool and must still request every
+recorded consent. `python3` and individual scanner executables remain system
+prerequisites and are never installed by the package.
+
+First inspect the host/tool availability without starting a scanner:
+
+```bash
+python3 /path/to/mnogovid-system-scanner/scripts/init.py /safe/report-directory --json
+```
+
+This manual initializer is optional; the unified workflow uses `system_bootstrap`
+first. A profile records discovery only and never grants scanner permission:
+
+```bash
+python3 /path/to/mnogovid-system-scanner/scripts/init.py /safe/report-directory --json --write
+```
+
+For every adapter the agent previews its exact argv and asks for approval. Two
+additional controls are deliberately separate:
+
+- Image scanners with external vulnerability databases require `network`
+  consent, an image reference, and per-scanner approval.
+- `nmap-local` needs recorded lifecycle active-network consent,
+  `authorizedTarget=true`, and one explicitly authorized literal IP.
+- Database clients require `serviceProbe` consent and use only fixed local,
+  read-only status commands. Their raw output is withheld after normalization.
+- `tshark-summary` needs recorded lifecycle traffic-capture consent, a named
+  interface, and a 5–300 second capture interval. It emits metadata to the
+  scanner result only, not a PCAP file; packet metadata can still be sensitive.
+
+The database adapters use fixed local read-only status/version commands. They
+can be unavailable when a service is not local, its socket is inaccessible, or
+it requires credentials; such a result is a coverage gap, not a clean bill of
+health.
+
+Reports are written only after `system_finalize_run`:
+
+```text
+<report-directory>/.mnogovid/system-scanner/<timestamp>/result.md
+```
+
+The report is reader-first: verdict, actionable findings, coverage gaps with
+recovery guidance, scanner coverage, security-relevant observations, recorded
+consent, and distinct AI/independent-review sections. A failed, missing, or
+declined adapter is a coverage gap—not a clean result.
+
+## AI and independent review
+
+The AI and independent-review modes create bounded, secret-redacted payloads
+only after their own separate approvals. Both assessments are advisory and
+remain distinct from the scanner evidence.
+
+Use `system_ingest` to normalize a pre-existing private local JSON or SARIF
+report inside the selected report directory without starting a process.
+`system_advisory_lookup` queries OSV for one
+package version only after a separate `allowNetwork=true` approval; it is
+advisory evidence and does not account for distribution backports by itself.
+
+## Development
+
+Validate the manifest and exercise the JSON-RPC server without starting a
+scanner:
+
+```bash
+python3 /path/to/plugin-creator/scripts/validate_plugin.py /path/to/mnogovid-system-scanner
+python3 -m unittest discover -s /path/to/mnogovid-system-scanner/tests -v
+```
+
+Licensed under the Apache License 2.0.
+
+## Troubleshooting
+
+- **Profile missing:** rerun the unified workflow and approve profile creation.
+- **Profile invalid:** stop and repair it explicitly; the workflow will not
+  scan through an invalid profile.
+- **Adapter missing or permission denied:** install or grant the required
+  read-only access through normal system administration, then rerun bootstrap.
+- **Remote MCP unavailable:** verify the SSH alias, known host key, remote
+  Python path, and remote plugin path; the generator does not contact the
+  server or modify `~/.codex/config.toml`.
+- **No findings:** a completed set of checks cannot prove the absence of
+  compromise, unseen traffic, or kernel-level stealth. Review coverage gaps.

package/opencode.js

@@ -0,0 +1,115 @@
+import { spawn } from "node:child_process"
+import { fileURLToPath } from "node:url"
+import { tool } from "@opencode-ai/plugin"
+
+const METHODS = new Set([
+  "system_catalog",
+  "system_doctor",
+  "system_bootstrap",
+  "system_plan",
+  "system_virtual_run",
+  "system_run",
+  "system_ingest",
+  "system_start_run",
+  "system_record_run",
+  "system_finalize_run",
+  "system_ai_triage_payload",
+  "system_advisory_lookup",
+])
+
+class PythonMcpBridge {
+  constructor(script) {
+    this.nextId = 1
+    this.pending = new Map()
+    this.buffer = ""
+    this.queue = Promise.resolve()
+    this.stderr = ""
+    this.child = spawn("python3", [script], { stdio: ["pipe", "pipe", "pipe"] })
+    this.child.stdout.setEncoding("utf8")
+    this.child.stdout.on("data", (chunk) => this.receive(chunk))
+    this.child.stderr.setEncoding("utf8")
+    this.child.stderr.on("data", (chunk) => {
+      this.stderr = (this.stderr + chunk).slice(-4096)
+    })
+    this.child.on("error", (error) => this.failAll(error))
+    this.child.on("exit", (code, signal) => {
+      this.failAll(new Error(`Python scanner exited (${signal ?? code ?? "unknown"})${this.stderr ? `: ${this.stderr}` : ""}`))
+    })
+    process.once("exit", () => this.child.kill())
+  }
+
+  receive(chunk) {
+    this.buffer += chunk
+    let newline
+    while ((newline = this.buffer.indexOf("\n")) >= 0) {
+      const line = this.buffer.slice(0, newline)
+      this.buffer = this.buffer.slice(newline + 1)
+      if (!line.trim()) continue
+      try {
+        const message = JSON.parse(line)
+        const pending = this.pending.get(message.id)
+        if (!pending) continue
+        this.pending.delete(message.id)
+        if (message.error) pending.reject(new Error(message.error.message ?? "Python scanner protocol error"))
+        else pending.resolve(message.result)
+      } catch (error) {
+        this.failAll(new Error(`Invalid response from Python scanner: ${error.message}`))
+      }
+    }
+  }
+
+  failAll(error) {
+    for (const { reject } of this.pending.values()) reject(error)
+    this.pending.clear()
+  }
+
+  call(method, args) {
+    const request = () => new Promise((resolve, reject) => {
+      if (this.child.exitCode !== null || this.child.killed) {
+        reject(new Error("Python scanner is unavailable; verify that python3 is installed."))
+        return
+      }
+      const id = this.nextId++
+      this.pending.set(id, { resolve, reject })
+      this.child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method: "tools/call", params: { name: method, arguments: args } })}\n`)
+    })
+    const result = this.queue.then(request, request)
+    this.queue = result.catch(() => undefined)
+    return result
+  }
+}
+
+function parseArguments(raw) {
+  try {
+    const value = JSON.parse(raw)
+    if (!value || Array.isArray(value) || typeof value !== "object") throw new Error("must be a JSON object")
+    return value
+  } catch (error) {
+    throw new Error(`argumentsJson ${error.message}`)
+  }
+}
+
+export const MnogovidSystemScanner = async () => {
+  const script = fileURLToPath(new URL("./scripts/system_mcp.py", import.meta.url))
+  const bridge = new PythonMcpBridge(script)
+
+  return {
+    tool: {
+      mnogovid_system_scanner: tool({
+        description: "Call one consent-gated Mnogovid System Scanner operation. Valid operations: system_catalog, system_doctor, system_bootstrap, system_plan, system_virtual_run, system_run, system_ingest, system_start_run, system_record_run, system_finalize_run, system_ai_triage_payload, system_advisory_lookup. Pass argumentsJson as a JSON object. The Python core validates report directories, recorded lifecycle and consent before any scanner starts.",
+        args: {
+          operation: tool.schema.string(),
+          argumentsJson: tool.schema.string(),
+        },
+        async execute({ operation, argumentsJson }) {
+          if (!METHODS.has(operation)) return `Unknown Mnogovid System Scanner operation: ${operation}`
+          try {
+            return JSON.stringify(await bridge.call(operation, parseArguments(argumentsJson)))
+          } catch (error) {
+            return JSON.stringify({ error: error.message })
+          }
+        },
+      }),
+    },
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@bergabruh/system-scanner",
+  "version": "0.1.0",
+  "description": "OpenCode plugin for consent-gated Linux host security assessment.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./opencode.js",
+  "module": "./opencode.js",
+  "exports": "./opencode.js",
+  "files": [
+    "opencode.js",
+    "scripts/*.py",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "security",
+    "linux"
+  ],
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.18.11"
+  },
+  "scripts": {
+    "check": "node --check opencode.js"
+  },
+  "homepage": "https://github.com/BergaBruh/mnogovid",
+  "repository": { "type": "git", "url": "git+https://github.com/BergaBruh/mnogovid.git" }
+}

package/scripts/init.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""Initialize an optional, non-destructive Mnogovid System Scanner profile."""
+from __future__ import annotations
+
+import argparse
+import json
+import platform
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+
+from system_mcp import atomic_write, plan, report_directory
+
+PROFILE_NAME = ".mnogovid-system-scanner.json"
+PACKAGE_MANAGER_HINTS = (
+    ("apt", "apt-get", "sudo apt-get install <package>"),
+    ("dnf", "dnf", "sudo dnf install <package>"),
+    ("yum", "yum", "sudo yum install <package>"),
+    ("pacman", "pacman", "sudo pacman -S <package>"),
+    ("zypper", "zypper", "sudo zypper install <package>"),
+    ("apk", "apk", "sudo apk add <package>"),
+)
+
+
+def installation_guide(missing: list[str]) -> dict[str, object]:
+    return {
+        "message": "Install missing scanners only through your normal system administration process; this plugin never installs tools.",
+        "platform": platform.platform(),
+        "missingExecutables": missing,
+        "packageManagers": [{"name": name, "executable": executable, "commandTemplate": command} for name, executable, command in PACKAGE_MANAGER_HINTS if shutil.which(executable)],
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Inspect available Linux host-security scanners without running them.")
+    parser.add_argument("report_directory", nargs="?", default=".", help="existing directory where optional profile and reports live")
+    parser.add_argument("--write", action="store_true", help=f"create {PROFILE_NAME} if absent")
+    parser.add_argument("--force", action="store_true", help="replace an existing profile; requires --write")
+    parser.add_argument("--allow-active-network", action="store_true", help="record a preference for later explicitly approved Nmap probes")
+    parser.add_argument("--allow-network", action="store_true", help="record a preference for later explicitly approved vulnerability-database use")
+    parser.add_argument("--allow-service-probe", action="store_true", help="record a preference for later explicitly approved local service status probes")
+    parser.add_argument("--allow-traffic-capture", action="store_true", help="record a preference for later explicitly approved bounded packet summaries")
+    parser.add_argument("--json", action="store_true", help="print JSON")
+    args = parser.parse_args()
+    if args.force and not args.write:
+        parser.error("--force requires --write")
+    root = report_directory(args.report_directory)
+    result = plan(root)
+    result["missingExecutables"] = [item["executable"] for item in result["runs"] if not item["available"]]
+    result["installationGuide"] = installation_guide(result["missingExecutables"])
+    profile_path = root / PROFILE_NAME
+    exists = profile_path.exists() or profile_path.is_symlink()
+    if exists and profile_path.is_symlink():
+        parser.error(f"refusing to write through symlinked profile: {profile_path}")
+    if args.write and (not exists or args.force):
+        profile = {
+            "schemaVersion": 1,
+            "generatedBy": "mnogovid-system-scanner init",
+            "generatedAt": datetime.now(timezone.utc).replace(microsecond=0).isoformat(),
+            "allowActiveNetwork": args.allow_active_network,
+            "allowNetwork": args.allow_network,
+            "allowTrafficCapture": args.allow_traffic_capture,
+            "allowServiceProbe": args.allow_service_probe,
+            "availableAdapters": [item["adapter"] for item in result["runs"] if item["available"]],
+            "recommendedAdapters": result["recommendedAdapters"],
+            "installationGuide": result["installationGuide"],
+            "notes": ["This file does not run scanners or grant per-command consent.", "Active probing and traffic capture still require an explicit tool call and user approval."],
+        }
+        atomic_write(profile_path, json.dumps(profile, ensure_ascii=False, indent=2) + "\n", replace=args.force)
+        result["profile"] = {"path": str(profile_path), "action": "replaced" if exists else "created"}
+    elif args.write:
+        result["profile"] = {"path": str(profile_path), "action": "unchanged", "reason": "already exists"}
+    else:
+        result["profile"] = {"path": str(profile_path), "action": "not_written"}
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        host_os = result["host"].get("os", {})
+        print(f"Host: {host_os.get('pretty_name', host_os.get('system', 'unknown'))}")
+        for item in result["runs"]:
+            print(f"- {item['adapter']}: {item['executable']} ({'available' if item['available'] else 'missing'})")
+        for manager in result["installationGuide"]["packageManagers"]:
+            print(f"- Installation template ({manager['name']}): {manager['commandTemplate']}")
+        print(f"Profile: {result['profile']['action']} ({profile_path})")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/remote_mcp_config.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+"""Render a safe static Codex MCP stanza for one SSH alias.
+
+The script prints TOML; it deliberately never edits ~/.codex/config.toml and
+never contacts the remote host. The SSH alias must already exist locally.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+
+
+def validate_alias(value: str) -> str:
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,63}", value):
+        raise ValueError("SSH alias must contain only letters, digits, dot, underscore, or hyphen")
+    return value
+
+
+def validate_remote_script(value: str) -> str:
+    if not value.startswith("/") or ".." in value.split("/") or not re.fullmatch(r"/[A-Za-z0-9_./-]+", value):
+        raise ValueError("remote script must be an absolute path without '..' or whitespace")
+    return value
+
+
+def render(alias: str, remote_script: str) -> str:
+    alias = validate_alias(alias)
+    remote_script = validate_remote_script(remote_script)
+    server_name = "mnogovid_system_" + re.sub(r"[^A-Za-z0-9_]", "_", alias)
+    arguments = ["-T", "-o", "BatchMode=yes", "-o", "ClearAllForwardings=yes", "-o", "ForwardAgent=no", "-o", "StrictHostKeyChecking=yes", alias, "/usr/bin/python3", remote_script]
+    return "\n".join([f"[mcp_servers.{server_name}]", 'command = "ssh"', "args = [" + ", ".join(json.dumps(item) for item in arguments) + "]", ""]) 
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Render a static SSH-stdio MCP config stanza.")
+    parser.add_argument("ssh_alias", help="existing safe SSH alias from ~/.ssh/config")
+    parser.add_argument("--remote-script", default="/opt/mnogovid-system-scanner/scripts/system_mcp.py")
+    args = parser.parse_args()
+    try:
+        sys.stdout.write(render(args.ssh_alias, args.remote_script))
+    except ValueError as exc:
+        parser.error(str(exc))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())