@topy-ai/maggie 0.7.55 → 0.7.57

package/bundled-skills/maggie-security/references/commands.md

@@ -0,0 +1,125 @@
+# Commands
+
+Every command takes the common flags: `--project PATH`, `--site ID`,
+`--format json|sarif|md|text`, `--output FILE`, `--fail-on SEVERITY`, `--ci`,
+`--offline`, `--since 24h`, `--max-items N`, `--no-ledger`, `--explain-egress`.
+
+Exit codes: 0 ok · 1 findings at/above `--fail-on` · 2 usage · 3 degraded
+(a source or tool did not answer) · 4 refused by policy · 5 scanner missing
+or checksum mismatch.
+
+## Housekeeping
+
+| Command | What it does |
+|---|---|
+| `maggie security doctor [--fix]` | site type, domains, applicable checks, tools, feed freshness, consents, ledger counts; `--fix` writes `config.json` and the `.gitignore` entry |
+| `maggie security tools list\|install\|verify [--tool NAME]` | pinned external scanners in `~/.cache/maggie/security-tools/`; refuses unpinned or mismatched binaries |
+| `maggie security feeds status\|sync\|verify [--source ID]` | the feed cache under `.maggie/security/feeds/` |
+| `maggie security ledger list\|show\|accept\|false-positive\|reopen\|compact` | finding status history; `accept` and `false-positive` need `--reason` |
+| `maggie security consent grant\|revoke\|list --host ALIAS --level ssh-read` | per-host consent; granting is interactive only |
+
+## Vulnerability intelligence
+
+| Command | What it does | Sources contacted |
+|---|---|---|
+| `maggie security inventory` | builds `stack.json` from lockfiles, manifests, images, version files, JS bundles, WordPress and host evidence | none |
+| `maggie security vuln-watch [--sources osv,node,wp,software,cvelistv5,kev,epss]` | matches the stack against every source | api.osv.dev, raw.githubusercontent.com, www.wpvulnerability.net, api.first.org |
+| `maggie security osv-query --purl … \| --ecosystem --name --version \| --id … \| --stack` | one package, one advisory, or the whole stack | api.osv.dev |
+| `maggie security wp-check` | WordPress core, plugins, themes; PHP/web server/database versions | www.wpvulnerability.net |
+| `maggie security eol-watch [--product php=8.1]` | end of life and patch-behind for runtimes, databases, servers, distros, frameworks | endoflife.date (snapshot offline) |
+| `maggie security node-check [--node-version 20.11.1]` | Node.js core advisories | raw.githubusercontent.com |
+| `maggie security advisory --cve ID --component php \| --finding msf_…` | writes a `runtime-inventory --advisory` file | raw.githubusercontent.com, endoflife.date |
+
+`--explain-egress` on any command prints the hosts it may contact. Only
+package names and versions are sent to OSV; lockfiles, code, logs and
+findings never leave the machine.
+
+## Deploy gate
+
+| Command | What it does | Sources contacted |
+|---|---|---|
+| `maggie security deps [--engine auto\|osv-scanner\|native] [--lockfiles-only\|--bundles-only] [--include-dev] [--ci]` | every lockfile ecosystem plus JavaScript copied into the site (retire.js repository); the pinned osv-scanner when installed, else the native OSV engine; `--offline` matches against `.maggie/security/db/osv` | api.osv.dev, raw.githubusercontent.com |
+| `maggie security secrets [--scope git,tree,dist] [--engine auto\|gitleaks\|native] [--baseline FILE\|--write-baseline FILE]` | keys and passwords in git history, project files and build output, plus `.env` values copied into the build; gitleaks' 222 rules (MIT) and Maggie's; values never shown or stored | none |
+| `maggie security report --kind gate --output FILE` | gate decision (block / warn / pass) for `maggie deployment readiness --security-report FILE` | none |
+| `maggie security feeds mirror --dir DIR [--to-project]` | offline copy of every feed and the OSV ecosystem databases; point `MAGGIE_SECURITY_MIRROR` at it | every feed host |
+
+## Web surface (verified domains only)
+
+| Command | What it does | Contacted |
+|---|---|---|
+| `maggie security domain-verify start\|check\|status\|revoke --domain D [--method dns\|file]` | proves control of the registrable domain (TXT seen by the system resolver **and** DNS-over-HTTPS) or one host (file); valid 90 days, re-checked weekly | system resolver, cloudflare-dns.com, the site |
+| `maggie security headers --url U [--paths / /login] [--serving auto\|nginx\|apache\|cloudflare\|headers-file\|astro\|next\|php]` | grades security headers and cookies per path (ASVS 5.0 ids), plain-HTTP redirect, fix snippets for the serving layer; a new CSP is always suggested as Report-Only first | the site |
+| `maggie security tls --host H [--engine auto\|testssl\|native] [--ip ORIGIN]` | certificate trust and expiry, TLS 1.0/1.1 still accepted, TLS 1.3 missing; testssl.sh (GPL, installed by the person) when present | the site |
+| `maggie security web-scan --url U [--profile safe\|full-safe]` | httpx fingerprint, then nuclei with the safe profile (no intrusive, fuzz, DoS, brute-force, OAST templates; ≤ 10 req/s; one scan per domain at a time) | the site |
+| `maggie security zap-baseline --url U` | weekly passive ZAP baseline in Docker; header rules skipped (headers covers them) | the site |
+
+## Public check (sites you do NOT control — passive only)
+
+`public-check` is the one web command that does not need domain verification,
+because it only does what any visitor already does: one GET of the home page, a
+TLS handshake, and public DNS. It never probes paths, never submits anything,
+and never runs an active scanner. Use it to spot a visible problem on someone
+else's site and tell them. It is interactive-only (refused under `--ci` or in a
+routine) and never writes to the ledger. `web-scan`, `zap-baseline` and the host
+checks stay verified-only — do not run them against a site you do not control.
+
+| Command | What it does | Contacted |
+|---|---|---|
+| `maggie security public-check --url U` / `--domain D` (repeatable) / `--domains FILE` `[--outreach DIR] [--rate N] [--max-sites N]` | per site: security headers + cookies, TLS certificate and protocols, versions disclosed on the home page (`generator` meta, `Server`/`X-Powered-By`, JS libraries) matched to known CVEs (OSV, WPVulnerability, KEV, EPSS), missing/weak SPF and DMARC, and missing `security.txt`. `--outreach` writes a disclosure-ready note per domain (what is visible, no exploit detail). | the site, system resolver, cloudflare-dns.com, api.osv.dev, wpvulnerability.net, KEV, api.first.org |
+
+## Code
+
+| Command | What it does |
+|---|---|
+| `maggie security code-scan [--changed-since REF] [--rules maggie\|DIR] [--baseline FILE\|--write-baseline FILE]` | semgrep (LGPL, installed by the person, `--metrics=off`) with Maggie's 22-rule pack for Astro, React/Next, Node, PHP/WordPress, Dockerfile, nginx, plus native checks for root containers and served dotfiles; registry rules are refused |
+
+## Logs (read where they are; never uploaded)
+
+| Command | What it does |
+|---|---|
+| `maggie security logs-traffic --file access.log* [--since 7d] [--exclude-ip CIDR]` | requests, error rate, top pages/404s/addresses, crawler share, change against the last run; flags 5xx bursts and one address dominating |
+| `maggie security logs-sigma --file access.log [--rules web,proxy,emerging] [--min-level medium]` | 143 SigmaHQ web rules (DRL 1.1) on the log; attempts unless a webshell or secret file was served with content or an exploit for a CVE the site has got a normal response (then `compromise-indicator`, p0); `--list-rules` |
+| `maggie security logs-ioc --file access.log [--feeds blocklist-de,…]` | maltrail mass-scanner and user-agent lists (MIT); extra IP feeds only when you choose them after reading their terms; scores 0–100 |
+| `maggie security logs-remote --ssh web1=user@host [--pattern /xmlrpc.php]` | summary computed on the server by an inline awk program; nothing is written there and no log line comes back |
+
+Formats: nginx/Apache combined and vcombined, Caddy JSON, Cloudflare Logpush JSON; `.gz` files are fine.
+
+## Hosts (read-only unless stated)
+
+| Command | What it does | Consent |
+|---|---|---|
+| `maggie security host-quick --ssh web1=user@host \| --evidence FILE \| --print-collector` | SSH, firewall, automatic updates, fail2ban/CrowdSec and port alignment, databases listening publicly, Docker bypassing UFW, SUID, sudo logging, disk/memory; checks ported from vps-audit (MIT) | ssh-read |
+| `maggie security host-nginx-config --ssh web1=user@host \| --evidence FILE` | nginx -T and php -i rules: hidden files, PHP in uploads, PATH_INFO, old TLS/weak ciphers, HSTS, add_header inheritance, WordPress login limits, xmlrpc, key permissions | ssh-read |
+| `maggie security host-audit --ssh web1=user@host \| --evidence report.dat` | lynis (GPL, external) uploaded to a private /tmp folder under the host lock, removed afterwards (verified); hardening index and warnings | ssh-temp-write |
+| `maggie security incident start\|log\|close\|show\|list` | timeline for a CVE response; `report --kind incident` prints it | none |
+
+## Protect and assure
+
+| Command | What it does |
+|---|---|
+| `maggie security protect-plan [create\|validate\|verify] --host web1 [--engine auto\|crowdsec\|fail2ban\|cloudflare] [--allow-ip IP] [--behind-cloudflare] [--log access.log]` | plan only: host lock first and last, a rollback per step, CrowdSec sharing off unless `--capi` (interactive), fail2ban WordPress filter tested on your log; `validate` rejects piped installers, unlisted downloads, missing rollbacks; `verify` checks the result read-only |
+| `maggie security uptime-init\|uptime-deploy\|uptime-status\|uptime-push` | Gatus config for verified domains (status, latency, certificate and domain expiry, brand text, DNS, redirect) and security-job heartbeats; a deploy plan (127.0.0.1, digest-pinned image); status findings; heartbeat pushes with short codes only |
+| `maggie security checklist [--level 1\|2\|3] [--profile …]` | OWASP ASVS 5.0 (read from OWASP at run time, CC BY-SA) filled from findings: pass only with positive coverage |
+| `maggie security threat-model [--include-findings]` | OWASP Threat Dragon v2 STRIDE draft |
+| `maggie security waf-replay --log access.log [--paranoia 2] [--threshold 5] [--exclude-bots]` | replays the log through Coraza + OWASP CRS v4 offline (helper `maggie-waf-replay`); share of real visitors each paranoia level would block, rules needing exclusions; feeds `protect-plan --replay-report` |
+| `maggie security sbom [--engine native\|syft] [--image REF]` | CycloneDX 1.5 SBOM |
+| `maggie security image REF` | trivy (vulns, secrets without values, misconfig, EOL base) + dockle |
+| `maggie security preinstall PKG[@V] [--threshold strict]` | npm package vetting: age, version age, install scripts, typosquats, OSV MAL-/vulns, Scorecard; never installs |
+| `maggie security exposure-check [--root DIR] [--deep] [--catalog-dir DIR]` | malicious packages already installed (OSV MAL- and incident catalogs) |
+| `maggie security skills-scan PATH [--kind mcp-registry] [--max-risk 50]` | SkillSpector (installed by you, `--no-llm` forced) |
+| `maggie security mcp-self-check [--registry FILE --mcp-tools FILE --server-config FILE --previous FILE]` | OWASP MCP checks MCP-01..MCP-15 |
+| `maggie security github-alerts --from-file alerts.json --repo OWNER/NAME` | Dependabot, code-scanning, secret-scanning alerts as findings (direct mode uses your own `GITHUB_TOKEN`) |
+
+## Hosted watch (CMO.so)
+
+| Command | What it does |
+|---|---|
+| `maggie security inventory --export-upload FILE --workspace example.com` | names and versions of packages, runtimes and WordPress items only — no paths, hosts, lockfiles, logs or secrets |
+| `maggie security hosted-job --stack-upload FILE --state-dir DIR --workspace example.com` | the server job: daily watch on the upload with per-workspace caps; returns a `report_save` payload only when something is new |
+
+## Reports and agents
+
+| Command | What it does |
+|---|---|
+| `maggie security report --kind weekly\|daily_ops\|incident\|gate [--audience owner\|technical] [--save]` | Markdown + JSON report from the latest runs; `--save` writes the `report_save` payload |
+| `maggie security mcp [--tools p0\|all] [--print-config claude\|codex]` | local stdio MCP server |

package/bundled-skills/maggie-security/references/cve-response.md

@@ -0,0 +1,24 @@
+# CVE response (W2)
+
+For a CVE in a runtime, database, web server or the OS. Steps 3–5 need the
+person; a routine never goes past step 2.
+
+1. `maggie security advisory --cve CVE-ID --component php` (or `--finding msf_…`)
+   → `.maggie/security/advisories/CVE-ID-php.json`:
+   `{"id", "component", "fixed": {"8.1": "8.1.29"}, "unsupportedLines": ["7.4"]}`.
+2. `maggie deployment runtime-inventory --ssh deploy@HOST --advisory FILE`
+   → affected sites and a migration plan per site. (Needs `ssh-read` consent.)
+   Components other than PHP are written with `"planner": "manual"`: describe
+   the upgrade yourself from the fixed versions.
+3. Show the plan: what changes, expected downtime, how to roll back. **Wait for approval.**
+4. `maggie deployment host-lock acquire --host HOST --session S --purpose "CVE-ID response"`.
+   If `host-lock status` shows recent changes by someone else, stop and ask.
+5. The person runs the plan, or you run it in this interactive session after
+   they approved that exact plan.
+6. Re-run step 2: it must show 0 affected sites.
+7. `maggie security vuln-watch` — the ledger marks the finding fixed only from a complete run.
+8. `maggie deployment host-lock release …`.
+9. `maggie security report --kind incident --save` with the timeline.
+
+No fix available: the plan is mitigation only (disable the feature, block the
+path, isolate the service) and the report says "no fix yet".

package/bundled-skills/maggie-security/references/explaining-findings.md

@@ -0,0 +1,57 @@
+# Explaining findings
+
+Four parts, plain words, one action per finding:
+
+> **What we found:** … **Why it matters:** … **What to do:** … **How urgent:** …
+
+Urgency words: p0 today · p1 this week · p2 this month · p3 when convenient · p4 for information.
+No CVSS vectors, purls or rule ids for site owners; keep them for developers.
+Name components the way the owner sees them (the plugin's name in WordPress,
+"your database (MySQL 5.7)", "the server's operating system (Ubuntu 20.04)").
+
+## vulnerability
+
+> **What we found:** Your site uses Next.js 14.2.10.
+> **Why it matters:** A flaw in this version lets visitors skip login checks. Attackers are using it now.
+> **What to do:** Update Next.js to 14.2.25, rebuild and redeploy.
+> **How urgent:** Today.
+
+When there is no fix: say "no fixed version yet", list what reduces the risk
+(turn the feature off, block the path, replace the package) and never invent
+a version.
+
+## vulnerability on a runtime, database or server
+
+> **What we found:** The server web1 runs PHP 7.4.33.
+> **Why it matters:** PHP 7.4 has a known flaw that attackers use to run commands, and it gets no more fixes.
+> **What to do:** Move the site to PHP 8.3. I can prepare the plan; you approve it before anything changes.
+> **How urgent:** Today.
+
+## eol
+
+> **What we found:** Your database is PostgreSQL 12.
+> **Why it matters:** It stopped getting security fixes on 2024-11-21, so new flaws will not be fixed.
+> **What to do:** Plan an upgrade to PostgreSQL 17 or 18.
+> **How urgent:** This week to plan; schedule the move this month.
+
+Patch-behind (`info`): "PostgreSQL 16.2 is behind the latest 16.x update (16.6). Apply it at the next maintenance window."
+
+## malicious-package
+
+> **What we found:** The package `x` in your project is known to be malicious.
+> **Why it matters:** It was published to steal data or keys.
+> **What to do:** Remove it now, rotate any keys on machines that installed it, and check the lockfile for how it got in.
+> **How urgent:** Today.
+
+## secret
+
+> **What we found:** An API key in `src/config.js` line 2 (`mgfx…5nMq`).
+> **Why it matters:** Anyone who can read that file can use the key.
+> **What to do:** Revoke the key with the provider first, then remove it from the code and history.
+> **How urgent:** Today.
+
+Never show the value; the preview (first 4 + last 4) is all there is.
+
+## possible matches
+
+> A new advisory names PostgreSQL but gives no version range. Worth a look: check whether 13.11 is listed on the vendor page.

package/bundled-skills/maggie-security/references/findings.md

@@ -0,0 +1,39 @@
+# Findings, priority and the ledger
+
+A finding (`contracts/maggie-security/finding-v1.schema.json`) names the
+site, the component and version, the fixed version, whether it is exploited
+(`kev`), how likely exploitation is (`epss`), the evidence and the fix.
+
+## Priority (first match wins)
+
+| Priority | When |
+|---|---|
+| p0 | on CISA KEV with a confirmed/likely match on an internet-facing component; a confirmed secret in a public file; a compromise indicator |
+| p1 | critical; high with EPSS ≥ 0.1; an internet-facing runtime past end of life |
+| p2 | high; medium with a fix on a direct dependency; end of life within 30 days |
+| p3 | medium/low; end of life within 90 days; hardening |
+| p4 | information; `possible` matches with no corroboration; dev-only |
+
+Dev-only scope lowers one step except for secrets.
+
+## Confidence
+
+- `confirmed`: exact version or range match from a package database.
+- `likely`: a CVE record's version range for a product name in the stack.
+- `possible`: the product is named but no range applies — "worth a look".
+
+## Status and the ledger
+
+`.maggie/security/ledger.jsonl` keeps one line per event. A finding is
+`new` the first time, `open` after that, `fixed` only when a complete run
+covered the same target and it was gone. A degraded run never marks
+anything fixed. `accepted-risk` expires (default 90 days) and comes back
+`open`; `false-positive` stays until reopened. A new KEV listing or a
+higher severity re-reports an open finding as `new` with `change: escalated`.
+
+Only mark a finding when the person says so:
+
+```bash
+maggie security ledger accept --id msf_… --reason "dev-only tool, not deployed" --until 2027-01-31
+maggie security ledger false-positive --id msf_… --reason "plugin folder renamed, different plugin"
+```

package/bundled-skills/maggie-security/references/ownership-and-consent.md

@@ -0,0 +1,29 @@
+# Ownership, consent and what leaves the machine
+
+| Level | Examples | How granted |
+|---|---|---|
+| read-local | lockfiles, logs on disk | implicit |
+| read-public | public feeds, OSV queries with package names | implicit; `--offline` refuses |
+| scan-owned | headers/TLS/web scans of a verified domain | `maggie security domain-verify start` → the person adds the TXT record → `check` |
+| ssh-read | `inventory --ssh` | `maggie security consent grant --host web1 --level ssh-read`, typed by the person |
+| host-change | installing or editing anything on a server | never by a security command |
+
+Sent off the machine: package names and versions (OSV), plugin slugs and
+versions (WPVulnerability), CVE ids (FIRST EPSS). Never: lockfile contents,
+code, logs, host evidence, secrets, findings. `--explain-egress` lists the
+hosts per command; `--offline` makes no connections and uses the cache and
+packaged snapshots.
+
+## Verifying a domain
+
+1. `maggie security domain-verify start --domain example.com` prints a TXT
+   record: name `_maggie-security.example.com`, value
+   `maggie-site-verification=<token>`. The token is shown once; only its hash is kept.
+2. The person adds it at their DNS provider.
+3. `maggie security domain-verify check --domain example.com` passes when the
+   system resolver and a public DNS-over-HTTPS resolver both see it. The record
+   covers the registrable domain and its subdomains for 90 days and is
+   re-checked every 7 days; removing the TXT record ends scanning within a week.
+
+`--method file` instead serves the token at
+`https://host/.well-known/maggie-security-verification.txt` and covers that host only.

package/bundled-skills/maggie-security/references/site-types.md

@@ -0,0 +1,22 @@
+# Site types and stacks
+
+`maggie security doctor` detects the site type; `inventory` reads whatever
+is present, so mixed projects work.
+
+| Stack | Inventory reads | Matched by |
+|---|---|---|
+| JavaScript/TypeScript | package-lock, npm-shrinkwrap, pnpm-lock, yarn.lock, bun.lock, package.json pins, shipped `*.js` bundles | OSV (npm) |
+| PHP | composer.lock; PHP version from hosts/images | OSV (Packagist); WPVulnerability (php); endoflife.date |
+| Python | requirements*.txt pins, Pipfile.lock, poetry.lock, uv.lock, pdm.lock, `.python-version`, runtime.txt | OSV (PyPI); endoflife.date |
+| Java/Kotlin | pom.xml (properties resolved), gradle.lockfile, Spring Boot parent | OSV (Maven); endoflife.date (Java, Spring Boot, Tomcat) |
+| Go | go.mod (+ `go` directive → Go standard library) | OSV (Go, Go/stdlib); endoflife.date |
+| Ruby | Gemfile.lock (+ RUBY VERSION) | OSV (RubyGems); endoflife.date |
+| Rust | Cargo.lock | OSV (crates.io) |
+| .NET | packages.lock.json, *.csproj, Directory.Packages.props, global.json | OSV (NuGet); endoflife.date |
+| WordPress | core, plugins, themes from files (+ `wp plugin list --format=json` for active state) | WPVulnerability; endoflife.date |
+| Databases and servers | Dockerfile/compose images; host collector (`mysqld`, `postgres`, `redis-server`, `mongod`, `nginx`, `apache2`, `memcached`, `openssl`, `java`…) | WPVulnerability (php, nginx, apache, mysql, mariadb, redis, memcached, sqlite), CVE delta product match, endoflife.date |
+| Linux | `/etc/os-release`, dpkg/rpm/apk package lists from the host collector | OSV (Debian, Ubuntu, Alpine, Rocky, Alma); endoflife.date |
+
+Red Hat package lists are inventoried but OSV matching for RHEL needs
+repository-specific ecosystem names and is not done yet; RHEL hosts still get
+end-of-life and CVE product checks.

package/bundled-skills/maggie-security/references/tools-and-licences.md

@@ -0,0 +1,16 @@
+# Tools and licences
+
+Scanners are pinned in `tools/clis/security_data/tools.lock.json` with
+version, licence class and sha256 per platform. `maggie security tools
+install --tool NAME` downloads to `~/.cache/maggie/security-tools/`, checks
+the sha256 and never uses sudo. The runner refuses a changed binary (exit 5)
+and forbidden flags such as telemetry or cloud upload (exit 4), and adds the
+required ones (for example nuclei `-ni -duc`).
+
+| Class | Licences | Rule |
+|---|---|---|
+| bundle-ok | MIT, Apache-2.0, BSD, MPL-2.0 | may be called and redistributed with notices |
+| external-only | GPL, LGPL | installed by the person from upstream; called as a separate process |
+| reference-only | AGPL, BSL, ELv2 | design reference; not run by Maggie |
+
+Packaged data and its attribution: [data/LICENSE-NOTICE.md](../data/LICENSE-NOTICE.md).

package/bundled-skills/maggie-security/references/workflows.md

@@ -0,0 +1,23 @@
+# Workflows
+
+## W1 Daily watch
+
+```bash
+maggie security inventory            # when lockfiles, Dockerfiles or host evidence changed
+maggie security vuln-watch           # OSV, Node core, WPVulnerability, CVE delta, KEV, EPSS
+maggie security eol-watch            # end of life and patch-behind
+maggie security report --kind daily_ops --save
+```
+
+- Notify only for `status: new` at p0/p1, or an `escalated` finding.
+- `p0`/`p1` findings on a runtime, database, server or OS also write
+  `.maggie/security/advisories/<CVE>-<component>.json` for W2.
+- A degraded source is named in the report; nothing is marked fixed from it.
+
+Scheduling: off the hour (06:17), after the server's own jobs; check with
+`maggie ops routines-check routines.json`. Example: `routines.example.json`
+in this folder.
+
+## W2 CVE response
+
+See [CVE response](cve-response.md).