nsauditor-ai-agent-skill 0.2.52 → 0.2.53

package/references/schemas.md

@@ -6,79 +6,86 @@ Complete data structures for all MCP tool inputs and outputs.
 
 ## Scan Result Schema (`scan_host` output)
 
-The Result Concluder (plugin 008) fuses all plugin outputs into a normalized structure:
+`scan_host` returns the plugin run itself, with the Result Concluder's fused record inside it:
 
 ```json
 {
-  "summary": {
-    "host": "192.168.1.1",
-    "scan_time": "2026-04-11T12:00:00.000Z",
-    "duration_ms": 15432,
-    "plugins_run": 16,
-    "plugins_succeeded": 14,
-    "plugins_failed": 2,
-    "services_found": 8,
-    "findings_count": 3
-  },
-  "host": {
-    "ip": "192.168.1.1",
-    "hostname": "router.local",
-    "os": {
-      "family": "Linux",
-      "distro": "Ubuntu",
-      "version": "22.04",
-      "confidence": "high",
-      "source": "os_detector"
-    },
-    "mac": "AA:BB:CC:DD:EE:FF",
-    "vendor": "Ubiquiti",
-    "names": {
-      "mdns": "router.local",
-      "netbios": "ROUTER",
-      "upnp": "Ubiquiti EdgeRouter",
-      "dns_reverse": "router.example.com"
-    }
-  },
-  "services": [
-    {
-      "port": 22,
-      "protocol": "tcp",
-      "service": "ssh",
-      "program": "OpenSSH",
-      "version": "8.9p1",
-      "status": "open",
-      "banner": "SSH-2.0-OpenSSH_8.9p1 Ubuntu-3ubuntu0.4",
-      "info": null,
-      "source": "ssh_scanner",
-      "authoritative": true,
+  "host": "192.168.1.1",
+  "conclusion": {
+    "id": "008",
+    "name": "Result Concluder",
+    "result": {
+      "summary": "Host is UP — OS: Linux — Open: ssh/22, http/80",
+      "host": {
+        "up": true,
+        "os": "Linux",
+        "osVersion": null,
+        "name": null
+      },
+      "services": [
+        {
+          "port": 22,
+          "protocol": "tcp",
+          "service": "ssh",
+          "program": "OpenSSH",
+          "version": "8.9p1",
+          "status": "open",
+          "info": null,
+          "banner": "SSH-2.0-OpenSSH_8.9p1 Ubuntu-3ubuntu0.4",
+          "source": "ssh",
+          "evidence": [
+            {
+              "probe_protocol": "tcp",
+              "probe_port": 22,
+              "probe_info": "banner grab",
+              "response_banner": "SSH-2.0-OpenSSH_8.9p1 Ubuntu-3ubuntu0.4"
+            }
+          ],
+          "cpe": "cpe:2.3:a:openbsd:openssh:8.9p1:*:*:*:*:*:*:*"
+        }
+      ],
       "evidence": [
         {
-          "probe_protocol": "tcp",
-          "probe_port": 22,
-          "probe_info": "banner grab",
-          "response_banner": "SSH-2.0-OpenSSH_8.9p1 Ubuntu-3ubuntu0.4"
+          "from": "Ping Checker",
+          "protocol": "icmp",
+          "port": 0,
+          "status": null,
+          "info": "Ping did not confirm host up"
         }
-      ]
+      ],
+      "source_count": 26,
+      "os_source": "013"
     }
-  ],
-  "findings": [
+  },
+  "manifest": [
+    {
+      "id": "003",
+      "name": "Port Scanner",
+      "status": "ran",
+      "reason": null,
+      "duration_ms": 6016
+    },
     {
-      "id": "FINDING-001",
-      "category": "CRYPTO",
-      "severity": "HIGH",
-      "title": "TLSv1.0 supported",
-      "description": "Port 443 accepts TLSv1.0 connections which are deprecated.",
-      "evidence": { "port": 443, "protocol": "tcp", "tls_version": "TLSv1" },
-      "remediation": "Disable TLSv1.0 in the server configuration.",
-      "cwe": "CWE-326",
-      "mitre_attack": ["T1557"],
-      "verified": false,
-      "confidence": "high"
+      "id": "070",
+      "name": "MCP Scanner",
+      "status": "timeout",
+      "reason": "Plugin \"MCP Scanner\" timed out after 30000ms",
+      "duration_ms": 30001
     }
-  ]
+  ],
+  "pluginsRan": 55,
+  "markdown": "# NSAuditor AI Scan Report …"
 }
 ```
 
+- `conclusion.result.summary` is a **one-line string**, not an object.
+- `conclusion.result.services[]` has one record per discovered or probed service; each carries its own
+  `evidence[]` and, where one could be built, a `cpe` for `get_vulnerabilities`.
+- `manifest[]` is every plugin's run status: `ran`, `skipped` (with its `reason`), `timeout` or
+  `error`. A `timeout` or `error` means that surface was **NOT measured** — never read it as clean.
+- There is **no `findings` array** in a `scan_host` result, and no `techniques`: the CLI adds ATT&CK
+  techniques to its own report, and this tool does not.
+
 ---
 
 ## ServiceRecord Interface
@@ -188,71 +195,104 @@ export default {
 
 ---
 
-## Finding Schema
+## Finding Schema (the Pro / Enterprise finding queue)
 
-Structured finding format used across all tiers:
+Pro and Enterprise write a network host's findings to `scan_finding_queue.json` in that host's scan
+directory: the CVE engine's rows, the analysis agents' rows, and their coverage-gap records. Community
+never writes a queue. A CVE row, which carries every field:
 
 ```json
 {
-  "id": "F-<uuid-v4>",
-  "category": "AUTH | CRYPTO | CONFIG | SERVICE | EXPOSURE | CVE",
-  "severity": "CRITICAL | HIGH | MEDIUM | LOW | INFO",
-  "status": "UNVERIFIED | VERIFIED | POTENTIAL | FALSE_POSITIVE",
-  "title": "Short descriptive title",
-  "description": "Detailed explanation of the finding",
+  "id": "F-e36aa296-e81d-4986-a5ed-66cc36897c06",
+  "category": "CVE",
+  "status": "UNVERIFIED",
+  "title": "CVE-2020-25681 — udp/dns",
+  "description": "A flaw was found in dnsmasq before version 2.83. A heap-based buffer overflow …",
+  "severity": "HIGH",
+  "cvss": 8.1,
   "target": {
     "host": "192.168.1.1",
-    "port": 22,
-    "protocol": "tcp"
+    "port": 53,
+    "protocol": "udp",
+    "service": "dns",
+    "program": "dnsmasq",
+    "version": "2.78"
   },
   "evidence": {
-    "banner": "OpenSSH_7.4",
-    "version": "7.4p1 Debian",
-    "detectionMethod": "SSH banner grabbing",
-    "verification": {
-      "probeType": "safe-connect",
-      "timestamp": "2026-04-11T12:00:00Z",
-      "result": "confirmed"
+    "source": "intelligence_engine",
+    "cve": [
+      "CVE-2020-25681"
+    ],
+    "mitre": [
+      "T1590.002 — Gather Victim Network Information: DNS"
+    ],
+    "raw": {
+      "cpe": "cpe:2.3:a:thekelleys:dnsmasq:2.78:*:*:*:*:*:*:*",
+      "cvssVector": "CVSS:3.1/AV:N/AC:H/PR:N/UI:N/S:U/C:H/I:H/A:H",
+      "published": "2021-01-20T17:15:00.000"
     }
   },
   "remediation": {
-    "action": "Upgrade OpenSSH to 9.x+",
-    "priority": "HIGH",
-    "timeline": "Immediate"
+    "summary": "Update dnsmasq 2.78 to a patched version. See CVE-2020-25681.",
+    "effort": "MEDIUM",
+    "references": [
+      "https://nvd.nist.gov/vuln/detail/CVE-2020-25681"
+    ]
   },
-  "cwe": "CWE-326",
-  "mitre_attack": ["T1021.004"],
-  "cves": ["CVE-2023-38408"],
-  "verified": false,
-  "confidence": "high | medium | low"
+  "riskScore": 0.49,
+  "kev": false,
+  "knownRansomwareCampaignUse": null,
+  "kevMatchedCve": null,
+  "kevAsOf": "2026-09-18T19:00:05.0974Z",
+  "kevStoreState": "fresh",
+  "epssScore": 0.81191,
+  "epssPercentile": 0.99616,
+  "epssMatchedCve": "CVE-2020-25681",
+  "epssAsOf": "2026-09-20T12:00:23Z",
+  "epssModelVersion": "v2026.06.15",
+  "epssStoreState": "fresh",
+  "exploitPriority": "ELEVATED",
+  "exploitPriorityReason": null
 }
 ```
 
+**Every row:** `id` · `category` · `status` · `title` · `severity` · `cvss` · `target` · `evidence` · `remediation` · `riskScore`
+
+**Most rows:** `description` — the analysis agents' own findings omit it: `auth_agent` · `config_agent` · `crypto_agent` · `exposure_agent` · `service_agent`. The CVE engine's rows and every coverage-gap record carry it.
+
+**CVE-bearing rows, once KEV / EPSS data is loaded:** `kev` · `knownRansomwareCampaignUse` · `kevMatchedCve` · `kevAsOf` · `kevStoreState` · `epssScore` · `epssPercentile` · `epssMatchedCve` · `epssAsOf` · `epssModelVersion` · `epssStoreState` · `exploitPriority` · `exploitPriorityReason`
+
+- `id` is `F-<uuid-v4>`, assigned when the row is queued.
+- `target` is `{ host, port, protocol, service, program, version }`; `evidence` is `{ source, cve[], mitre[], raw }`,
+  where `raw` belongs to the producer (a CVE row's `cpe`, `cvssVector`, `published`; a coverage-gap row's
+  `evidenceGap`, `gapClass`, …); `remediation` is `{ summary, effort, references[] }` on every row.
+- `evidence.cwe[]` and `evidence.owasp[]` are accepted by the validator, but no shipped producer emits them.
+
+**Severities:** `CRITICAL` · `HIGH` · `MEDIUM` · `LOW` · `INFO`
+
 ### Finding Categories
 
-| Category | Description | Examples |
-|----------|-------------|---------|
-| `AUTH` | Authentication weaknesses | Default credentials, anonymous login, weak auth |
-| `CRYPTO` | Encryption / TLS issues | Weak ciphers, deprecated TLS, expired certificates |
-| `CONFIG` | Misconfigurations | Debug mode, dangerous HTTP methods, CORS misconfig |
-| `SERVICE` | Service-level risks | Exposed management ports, known CVEs |
-| `EXPOSURE` | Network exposure | Internet-facing services, broadcast protocols |
-| `CVE` | Known CVE matches | NVD-confirmed vulnerabilities |
+| Category | What produces it |
+|----------|------------------|
+| `AUTH` | Authentication checks: anonymous access, default credentials, password and cleartext logins |
+| `CRYPTO` | Transport-encryption checks: TLS versions, cipher suites, certificates, cleartext protocols |
+| `CONFIG` | Configuration checks: version disclosure, directory listing, debug endpoints, exposed legacy services |
+| `SERVICE` | End-of-life software checks |
+| `EXPOSURE` | Exposure checks: database, management and lateral-movement ports |
+| `CVE` | CVE matches from NVD for a detected program and version, and the engine's coverage-gap notes |
 
 ### Finding Statuses
 
 | Status | Meaning |
 |--------|---------|
-| `UNVERIFIED` | Detected by a scanner. **This is the status every finding carries today** — see the WITHDRAWN note below. |
-| `VERIFIED` | Reserved for the planned Verification Engine. No shipped code sets it. |
-| `POTENTIAL` | Reserved for the planned Verification Engine. No shipped code sets it. |
-| `FALSE_POSITIVE` | Set by an operator suppression, not by a probe. |
+| `UNVERIFIED` | Detected by a scanner. **Every row a scan writes carries this status.** |
+| `VERIFIED` | Reserved. No shipped code sets it; the Verification Engine that would have is WITHDRAWN and not planned. |
+| `POTENTIAL` | Reserved. No shipped code sets it; the Verification Engine that would have is WITHDRAWN and not planned. |
+| `FALSE_POSITIVE` | Reserved. No shipped code sets it on a queued row. (An operator suppression marks a compliance *violation* as a false positive — a different object, in the compliance pack.) |
 
-> **The Verification Engine is planned, not shipped** (withdrawn as a capability claim at EE
-> 0.32.7). The status field and its risk-weighting scaffolding exist — which is why the enum
-> is documented here — but the probe machinery that would populate `VERIFIED` / `POTENTIAL`
-> is WITHDRAWN and does not ship. Read `UNVERIFIED` as "this is what the scanner detected", never as
-> "this was tried and could not be confirmed".
+> **The Verification Engine is WITHDRAWN and not planned** (withdrawn as a capability claim at EE
+> 0.32.7; no release schedules it). Read `UNVERIFIED` as "this is what the scanner detected", never as "this was tried and
+> could not be confirmed".
 
 ---
 
@@ -261,28 +301,25 @@ Structured finding format used across all tiers:
 ```json
 {
   "cpe": "cpe:2.3:a:openbsd:openssh:8.9p1:*:*:*:*:*:*:*",
-  "totalResults": 3,
-  "vulnerabilities": [
+  "totalResults": 1,
+  "cves": [
     {
-      "cve_id": "CVE-2023-38408",
+      "cveId": "CVE-2023-38408",
       "description": "PKCS#11 feature in ssh-agent allows remote code execution...",
-      "published": "2023-07-20T00:00:00.000Z",
-      "lastModified": "2023-08-01T00:00:00.000Z",
-      "cvss": {
-        "version": "3.1",
-        "baseScore": 9.8,
-        "severity": "CRITICAL",
-        "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
-      },
-      "cwe": ["CWE-428"],
-      "references": [
-        "https://nvd.nist.gov/vuln/detail/CVE-2023-38408"
-      ]
+      "cvssScore": 9.8,
+      "severity": "CRITICAL",
+      "vectorString": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
+      "published": "2023-07-20T03:15:10.170",
+      "lastModified": "2023-08-01T00:00:00.000"
     }
   ]
 }
 ```
 
+- The CVSS fields (`cvssScore`, `severity`, `vectorString`) are NVD's v3.1 metric, else v3.0; a CVE with
+  neither carries `null` in all three.
+- `totalResults` counts the CVEs **returned** — after `maxResults`, if one was passed.
+
 ---
 
 ## SARIF Output Schema (CI/CD Integration)
@@ -362,11 +399,17 @@ Keys dropped entirely: `IP6`, `deviceWebPage`, `hardwareVersion`, `firmwareVersi
 
 ## Scan History Schema (JSONL)
 
-Each line in `.scan_history/` is one scan record:
+Every scan appends one line per host to `scan_history.jsonl` in its output directory (`--out`, default `out/`):
 
 ```jsonl
-{"timestamp":"2026-04-11T12:00:00Z","host":"192.168.1.1","pluginsRan":25,"services":8,"findings":3,"conclusion":{...}}
-{"timestamp":"2026-04-11T13:00:00Z","host":"192.168.1.1","pluginsRan":25,"services":8,"findings":2,"conclusion":{...}}
+{"timestamp":"2026-09-24T01:32:08.915Z","host":"192.168.1.1","servicesCount":12,"openPorts":[21,22,53,80,443],"os":"Embedded Linux","findingsCount":64,"findingsCountBasis":"loader-shaped-v2","tier":"enterprise","cloudFindingsCount":0,"services":[{"port":22,"protocol":"tcp","service":"ssh","version":"8.2p1"}]}
+{"timestamp":"2026-09-24T01:20:45.180Z","host":"aws","servicesCount":0,"openPorts":[],"os":null,"findingsCount":139,"findingsCountBasis":"loader-shaped-v2","tier":"enterprise","cloudFindingsCount":159,"services":[]}
 ```
 
-Used for CTEM delta/trend analysis. CE retains 7 days; Pro/Enterprise configurable.
+- `findingsCountBasis` and `tier` say what `findingsCount` counted. The scan-to-scan diff refuses to compare
+  two lines whose basis or tier differs, or whose tier is unknown, rather than reading the change as new
+  or resolved findings.
+- `cloudFindingsCount` is the raw number of findings the plugins returned (evidence gaps and scope
+  statements included); `findingsCount` is the report loader's shaped count, so the raw figure can exceed it.
+- Retention: Community keeps **7 days** (older lines are pruned after each scan); Pro and Enterprise keep
+  every line. Neither is configurable.

package/references/workflows.md

@@ -13,13 +13,14 @@ Step 1: list_plugins()
         → Understand available scanners, confirm what will run
 
 Step 2: scan_host({ host: "<target>" })
-        → Returns fused results: summary, host{os}, services[], findings[]
+        → Returns the run: conclusion.result (summary, host, services[]) and manifest[]
+        → A `timeout` or `error` in manifest[] means that surface was NOT measured
 
 Step 3: For each service with a detected program + version:
         → Construct CPE: cpe:2.3:a:<vendor>:<product>:<version>:*:*:*:*:*:*:*
         → get_vulnerabilities({ cpe: "<constructed_cpe>" })
 
-Step 4: Correlate CVEs with scan findings
+Step 4: Correlate CVEs with the services they were built from
         → Present prioritized list: Critical → High → Medium → Low
         → Include remediation guidance for each finding
 ```
@@ -85,9 +86,9 @@ Step 3: Analyze evidence for specific weaknesses:
 | 012 | OpenSearch Scanner | Elasticsearch/OpenSearch detection |
 | 014 | NetBIOS Scanner | SMB/NetBIOS enumeration |
 | 015 | SUN RPC Scanner | NFS, portmapper services |
-| 040 | TLS Cert & Cipher Auditor | Full certificate chain audit *(Pro)* |
-| 050 | TRIBE v2 Probe | Debug leaks, CORS misconfig *(Pro)* |
-| 060 | DNS Security Auditor | SPF/DKIM/DMARC, DNSSEC *(Pro)* |
+| 040 | TLS Cert & Cipher Auditor | Full certificate chain audit |
+| 050 | TRIBE v2 Probe | Debug leaks, CORS misconfig |
+| 060 | DNS Security Auditor | SPF/DKIM/DMARC, DNSSEC |
 
 ---
 
@@ -169,8 +170,8 @@ nsauditor-ai scan --host 192.168.1.0/24 --plugins all \
 - Rescans on configurable interval (minutes)
 - Delta detection: new services, removed services, version changes
 - Fires JSON POST webhook on changes exceeding severity threshold
-- Scan history stored in `.scan_history/` (JSONL format)
-- CE: 7-day retention; Pro/Enterprise: configurable
+- Scan history appended to `scan_history.jsonl` in the output directory (`--out`, default `out/`), one line per host
+- CE: 7-day retention; Pro/Enterprise: every line kept (neither is configurable)
 
 **Webhook Payload:**
 
@@ -266,9 +267,9 @@ User wants to...
 ├── Check a specific service/port       → probe_service (Pro)
 ├── Look up CVEs for software version   → get_vulnerabilities (Pro)
 ├── See available plugins               → list_plugins
-├── Audit TLS certificates              → probe_service with plugin 040 (Pro)
-├── Check DNS security (SPF/DKIM/DMARC) → probe_service with plugin 060 (Pro)
-├── Detect debug leaks / CORS issues    → probe_service with plugin 050 (Pro)
+├── Audit TLS certificates              → scan_host, or probe_service (Pro) with plugin 040
+├── Check DNS security (SPF/DKIM/DMARC) → scan_host, or probe_service (Pro) with plugin 060
+├── Detect debug leaks / CORS issues    → scan_host, or probe_service (Pro) with plugin 050
 ├── Scan a subnet                       → CLI: --host CIDR --parallel N
 ├── Set up continuous monitoring         → CLI: --watch --interval N
 ├── Compare two scans                   → CLI: diff the per-run out-dirs (no compare tool)
@@ -307,6 +308,13 @@ User wants to...
 3. NVD API rate limits apply — wait and retry if rate-limited
 4. Not all software has NVD entries; absence ≠ safety
 
+### "A CLI cloud scan says coverage UNVERIFIED and suggests checking credentials"
+
+1. Read `pluginStatus` in `scan_conclusion_raw.json` before the summary. If every cloud plugin there is `"status": "skipped"` with `"reason": "missing capabilities: cloudScanners"`, the cause is the licence tier: the cloud plugins require an Enterprise licence, and a Community or Pro install skips all of them.
+2. In that case the summary's advice ("Verify cloud credentials are configured and the CE platform is ≥ 0.1.30") names the wrong cause. This is a known limit of this release; the per-plugin skip reason is the true one. Do not tell the user to fix credentials.
+3. The run is still correctly NOT a clean verdict: nothing was measured.
+4. MCP `scan_cloud` does not reach this path; below Enterprise it refuses before scanning, with an upgrade message.
+
 ### "License gate (🔒) error"
 
 1. `probe_service` and `get_vulnerabilities` require Pro license