nsauditor-ai-agent-skill 0.1.10

package/examples/agent-interactions.md

@@ -0,0 +1,248 @@
+# NSAuditor AI — Example Agent Interactions
+
+Reasoning chains showing how an AI agent should use NSAuditor AI tools.
+
+---
+
+## Example 1: "Scan my router for vulnerabilities"
+
+**Agent reasoning:** User wants a full security audit. Use `scan_host` first, then
+`get_vulnerabilities` for each detected service with a version.
+
+```
+1. scan_host({ host: "192.168.1.1" })
+   → Result: {
+       summary: { services_found: 4, findings_count: 1 },
+       host: { os: "Linux", vendor: "Ubiquiti" },
+       services: [
+         { port: 22, service: "ssh", program: "OpenSSH", version: "8.9p1" },
+         { port: 53, service: "dns", program: "dnsmasq", version: "2.89" },
+         { port: 443, service: "https", program: "lighttpd", version: "1.4.69" },
+         { port: 161, service: "snmp", program: null, version: null }
+       ],
+       findings: [
+         { severity: "MEDIUM", title: "SNMP default community string 'public'" }
+       ]
+     }
+
+2. get_vulnerabilities({ cpe: "cpe:2.3:a:openbsd:openssh:8.9p1:*:*:*:*:*:*:*" })
+   → CVE-2023-38408 (CRITICAL 9.8), CVE-2023-48795 (MEDIUM 5.9)
+
+3. get_vulnerabilities({ cpe: "cpe:2.3:a:thekelleys:dnsmasq:2.89:*:*:*:*:*:*:*" })
+   → CVE-2023-50387 (HIGH 7.5) — KeyTrap DNS vulnerability
+
+4. get_vulnerabilities({ cpe: "cpe:2.3:a:lighttpd:lighttpd:1.4.69:*:*:*:*:*:*:*" })
+   → No known CVEs
+
+5. Present findings sorted by severity:
+   CRITICAL: CVE-2023-38408 — OpenSSH ssh-agent RCE (upgrade to 9.3p2+)
+   HIGH: CVE-2023-50387 — dnsmasq KeyTrap DoS (upgrade to 2.90+)
+   MEDIUM: CVE-2023-48795 — SSH Terrapin attack (upgrade OpenSSH)
+   MEDIUM: SNMP default community string (change community string)
+   INFO: SNMP on port 161 has no version — manual investigation recommended
+```
+
+---
+
+## Example 2: "What plugins does NSAuditor have?"
+
+**Agent reasoning:** Simple metadata query — use `list_plugins`.
+
+```
+1. list_plugins()
+   → Return formatted list grouped by category:
+
+   Core Scanners (17):
+   • 001 Ping Checker — ICMP/ARP reachability + TTL OS hints
+   • 002 SSH Scanner — SSH banner, version, weak algorithms
+   • 003 Port Scanner — TCP/UDP bulk scan (~1000 ports)
+   [... full list ...]
+
+   Discovery (6):
+   • 025 DB Scanner — MySQL, PostgreSQL, Redis detection
+   [... etc ...]
+```
+
+---
+
+## Example 3: "Check if port 443 on example.com has weak TLS"
+
+**Agent reasoning:** Targeted single-service probe — use `probe_service` with TLS scanner.
+
+```
+1. probe_service({ host: "example.com", pluginName: "011", port: 443 })
+   → Result: {
+       program: "nginx",
+       version: "1.24.0",
+       data: [{
+         probe_info: "TLS handshake",
+         tls_versions: ["TLSv1.2", "TLSv1.3"],
+         ciphers: ["TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256"],
+         weakProtocols: [],
+         weakCiphers: []
+       }]
+     }
+
+2. Analysis: No deprecated TLS versions found. TLSv1.0 and TLSv1.1 are NOT
+   supported. All cipher suites are strong (AES-256-GCM, ChaCha20).
+   Verdict: TLS configuration is secure.
+```
+
+---
+
+## Example 4: "Is Log4j 2.14.1 vulnerable?"
+
+**Agent reasoning:** Direct CVE lookup — no scan needed. Construct CPE and query.
+
+```
+1. get_vulnerabilities({
+     cpe: "cpe:2.3:a:apache:log4j:2.14.1:*:*:*:*:*:*:*",
+     maxResults: 10
+   })
+   → [
+       CVE-2021-44228 (Log4Shell) — CRITICAL 10.0 — RCE via JNDI injection
+       CVE-2021-45046 — CRITICAL 9.0 — Incomplete fix for Log4Shell
+       CVE-2021-45105 — HIGH 7.5 — DoS via crafted lookup
+       CVE-2021-44832 — MEDIUM 6.6 — RCE via JDBC appender
+     ]
+
+2. Present with urgency: "Log4j 2.14.1 is critically vulnerable to Log4Shell
+   (CVE-2021-44228, CVSS 10.0) which enables remote code execution. Upgrade
+   immediately to Log4j 2.17.1+ or migrate to a maintained logging framework."
+```
+
+---
+
+## Example 5: "Set up continuous monitoring for my subnet"
+
+**Agent reasoning:** CTEM is a CLI feature, not available via MCP. Advise with the
+correct CLI command.
+
+```
+Agent response:
+"Continuous monitoring uses the CLI's watch mode (not available via MCP tools).
+
+Run:
+  nsauditor-ai scan --host 192.168.1.0/24 --plugins all \
+    --watch --interval 15 \
+    --webhook-url https://your-webhook.example.com/alerts \
+    --alert-severity high
+
+This rescans every 15 minutes, detects changes (new/removed services, version
+changes, new findings), and sends webhook alerts for high+ severity changes.
+
+Scan history is stored in .scan_history/ as JSONL for trend analysis."
+```
+
+---
+
+## Example 6: "Audit DNS security for example.com" (Pro)
+
+**Agent reasoning:** Use the DNS Security Auditor plugin for comprehensive DNS assessment.
+
+```
+1. probe_service({ host: "example.com", pluginName: "060", port: 53 })
+   → Result: {
+       spf: { valid: true, record: "v=spf1 include:_spf.google.com ~all" },
+       dkim: { found: true, selectors: ["google"] },
+       dmarc: { valid: true, policy: "reject", rua: "dmarc@example.com" },
+       dnssec: { signed: false },
+       axfr: { allowed: false },
+       mx: [{ host: "alt1.gmail-smtp-in.l.google.com", starttls: true }],
+       caa: [{ value: "letsencrypt.org" }]
+     }
+
+2. Present findings:
+   ✅ SPF configured (includes Google)
+   ✅ DKIM found (google selector)
+   ✅ DMARC policy set to 'reject' (strongest setting)
+   ⚠  DNSSEC not enabled (recommended for integrity)
+   ✅ Zone transfer (AXFR) properly blocked
+   ✅ MX servers support STARTTLS
+   ✅ CAA restricts certificates to Let's Encrypt
+```
+
+---
+
+## Example 7: Error Handling — SSRF Block
+
+**Agent reasoning:** User asked to scan localhost, which triggers SSRF protection.
+
+```
+1. scan_host({ host: "127.0.0.1" })
+   → Error: "SSRF protection: loopback addresses are blocked"
+
+2. Agent response:
+   "NSAuditor AI blocks scanning of loopback addresses (127.x.x.x) as a security
+   measure. This prevents SSRF attacks when the scanner is exposed as an MCP tool.
+
+   If you need to scan your local machine, you have two options:
+   1. Use the CLI directly: nsauditor-ai scan --host 127.0.0.1
+   2. Set NSA_ALLOW_ALL_HOSTS=1 in the MCP server's environment
+
+   Note: Only enable this for legitimate local auditing, never in production
+   MCP deployments."
+```
+
+---
+
+## Example 8: Error Handling — License Gate
+
+**Agent reasoning:** User requested a Pro feature on Community Edition.
+
+```
+1. User: "Check vulnerabilities for OpenSSH 8.9"
+
+2. get_vulnerabilities({ cpe: "cpe:2.3:a:openbsd:openssh:8.9p1:*:*:*:*:*:*:*" })
+   → Error: "🔒 get_vulnerabilities requires a Pro license"
+
+3. Agent response:
+   "CVE lookup via NSAuditor requires a Pro license. Here are your options:
+
+   1. Start a free trial: nsauditor.com/ai/trial
+   2. Set NSAUDITOR_LICENSE_KEY in your MCP server environment
+   3. Manual lookup: search nvd.nist.gov for 'openssh 8.9' directly
+
+   Meanwhile, I can still run scan_host (available in Community Edition) to
+   detect the service and identify potential risks from the scan evidence."
+```
+
+---
+
+## Example 9: Full Audit with AI Report
+
+**Agent reasoning:** User wants a comprehensive security assessment with AI analysis.
+
+```
+1. Confirm: "I'll scan 192.168.1.1. Do you have authorization to audit this host?"
+   → User confirms
+
+2. scan_host({ host: "192.168.1.1" })
+   → 4 services detected, 2 findings
+
+3. get_vulnerabilities for each versioned service
+   → 5 CVEs found across 2 services
+
+4. Present consolidated report:
+
+   ═══════════════════════════════════════
+   Security Audit Report: 192.168.1.1
+   ═══════════════════════════════════════
+
+   Host: Linux (Ubuntu 22.04) — Ubiquiti device
+   Services: 4 (SSH, DNS, HTTPS, SNMP)
+   Findings: 7 total (1 Critical, 1 High, 3 Medium, 2 Info)
+
+   CRITICAL FINDINGS:
+   • CVE-2023-38408 (CVSS 9.8) — OpenSSH ssh-agent RCE
+     → Upgrade OpenSSH from 8.9p1 to 9.3p2+
+
+   HIGH FINDINGS:
+   • CVE-2023-50387 (CVSS 7.5) — dnsmasq KeyTrap DoS
+     → Upgrade dnsmasq from 2.89 to 2.90+
+
+   [... continued ...]
+
+   For AI-enhanced analysis with remediation priorities, enable AI:
+     AI_ENABLED=true AI_PROVIDER=ollama nsauditor-ai scan --host 192.168.1.1
+```

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "nsauditor-ai-agent-skill",
+  "version": "0.1.10",
+  "description": "AI Agent Skill for NSAuditor AI — gives any AI coding agent built-in knowledge of NSAuditor's MCP tools, schemas, plugins, and security audit workflows.",
+  "keywords": [
+    "nsauditor",
+    "ai-agent",
+    "ai-agent-skill",
+    "mcp",
+    "model-context-protocol",
+    "network-security",
+    "vulnerability-scanner",
+    "security-audit",
+    "skill",
+    "claude",
+    "claude-code",
+    "cursor",
+    "windsurf",
+    "copilot",
+    "ai-coding-agent",
+    "cve",
+    "nvd",
+    "mitre-attack",
+    "sarif",
+    "port-scanner",
+    "tls-audit",
+    "penetration-testing"
+  ],
+  "homepage": "https://github.com/nsasoft/nsauditor-ai-agent-skill",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nsasoft/nsauditor-ai-agent-skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nsasoft/nsauditor-ai-agent-skill/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Nsasoft US LLC",
+    "url": "https://www.nsauditor.com"
+  },
+  "files": [
+    "SKILL.md",
+    "README.md",
+    "LICENSE",
+    "references/",
+    "examples/"
+  ],
+  "peerDependencies": {
+    "nsauditor-ai": ">=0.1.10"
+  },
+  "peerDependenciesMeta": {
+    "nsauditor-ai": {
+      "optional": true
+    }
+  }
+}

package/references/plugins.md

@@ -0,0 +1,205 @@
+# NSAuditor AI — Plugin Catalog
+
+Complete reference of all scanner plugins, organized by category.
+
+---
+
+## Core Scanners (17)
+
+| ID | Name | Protocols | Ports | Priority | Requirements |
+|----|------|-----------|-------|----------|-------------|
+| 001 | Ping Checker | ICMP/ARP | — | 100 | — |
+| 002 | SSH Scanner | TCP | 22 | 200 | host: up, tcp_open: [22] |
+| 003 | Port Scanner | TCP/UDP | ~1000 ports | 150 | host: up |
+| 004 | FTP Banner Check | TCP | 21 | 200 | host: up, tcp_open: [21] |
+| 005 | Host Up Check | TCP/UDP | multi-probe | 110 | — |
+| 006 | HTTP Probe | TCP | 80, 443 | 300 | host: up |
+| 007 | SNMP Scanner | UDP | 161 | 300 | host: up |
+| 008 | Result Concluder | Meta | — | 100000 | — (always runs last) |
+| 009 | DNS Scanner | TCP/UDP | 53 | 300 | host: up |
+| 010 | Webapp Detector | HTTP | 80, 443 | 400 | host: up |
+| 011 | TLS Scanner | TCP | 443, 465, 563, 993, 995 | 350 | host: up, tcp_open |
+| 012 | OpenSearch Scanner | HTTP | 9200 | 400 | host: up |
+| 013 | OS Detector | Meta | — | 99000 | — (runs near-last) |
+| 014 | NetBIOS/SMB Scanner | UDP/TCP | 137, 445 | 300 | host: up |
+| 015 | SUN RPC Scanner | TCP/UDP | 111 | 300 | host: up |
+| 016 | WS-Discovery | UDP | 3702 | 300 | host: up |
+| 024 | TCP SYN Scanner | TCP (Nmap) | configurable | 140 | nmap installed, root/sudo |
+
+### Plugin Details
+
+**001 — Ping Checker:** ICMP echo with ARP fallback. Extracts TTL-based OS hints
+(TTL 64 = Linux, 128 = Windows, 255 = network device). Falls back to TCP SYN on
+port 80/443 if ICMP is blocked (`PING_FALLBACK=true`).
+
+**002 — SSH Scanner:** Parses SSH protocol banner to extract program + version.
+Detects weak key exchange algorithms (`diffie-hellman-group1-sha1`) and weak ciphers
+(`aes128-cbc`, `3des-cbc`). Reports `weakAlgorithms[]` and `weakCiphers[]`.
+
+**003 — Port Scanner:** Bulk TCP connect scan (~1000 common ports) with optional
+UDP probing. Banner sniffing on open ports. Results feed into port-gated plugins.
+
+**004 — FTP Banner Check:** FTP daemon enumeration. Detects anonymous login,
+extracts program/version from FTP banner (220 response).
+
+**005 — Host Up Check:** Multi-probe reachability: ICMP echo → TCP SYN (80, 443) →
+UDP (53, 161). More thorough than Ping Checker for firewalled hosts.
+
+**006 — HTTP Probe:** Extracts HTTP response headers (`Server`, `X-Powered-By`),
+detects redirects, extracts server tokens for vendor/program identification.
+
+**007 — SNMP Scanner:** Queries sysDescr, sysObjectID, sysName via `public` community.
+Extracts hardware model, firmware version, and OS details from OID responses.
+
+**008 — Result Concluder:** Meta-plugin that fuses ALL plugin outputs into a single
+normalized `conclusion` object with `host{}`, `services[]`, and `evidence[]`. Always
+runs last (priority 100000). Resolves conflicts via `authoritative` flag.
+
+**009 — DNS Scanner:** Sends `version.bind` CHAOS TXT query to extract DNS server
+version (ISC BIND, PowerDNS, etc.). Also performs A/AAAA record lookups.
+
+**010 — Webapp Detector:** Uses Wappalyzer fingerprinting engine to identify web
+technologies: CMS (WordPress, Drupal), frameworks (React, Angular), servers (Apache,
+nginx), CDNs, analytics, and more.
+
+**011 — TLS Scanner:** Probes for supported TLS protocol versions (SSLv3, TLSv1.0,
+TLSv1.1, TLSv1.2, TLSv1.3) and cipher suites. Flags deprecated protocols and weak
+ciphers. Timeout configurable via `TLS_SCANNER_TIMEOUT_MS`.
+
+**012 — OpenSearch Scanner:** Detects Elasticsearch/OpenSearch instances. Extracts
+cluster name, version, and underlying OS/Java info from the `GET /` endpoint.
+
+**013 — OS Detector:** Meta-plugin that derives the most likely OS from ALL collected
+evidence: TTL hints, SSH banners, HTTP headers, SNMP sysDescr, NetBIOS, MAC vendor
+OUI lookup. Runs at priority 99000 (after all probes, before Concluder).
+
+**014 — NetBIOS/SMB Scanner:** NetBIOS name service enumeration (UDP 137) and SMB2
+detection (TCP 445). Optionally attempts null session (`SMB_NULL_SESSION=true`) to
+enumerate shares and domain info.
+
+**015 — SUN RPC Scanner:** Queries RPC portmapper (port 111) to enumerate registered
+RPC services. Detects NFS, mountd, and other RPC-based services.
+
+**016 — WS-Discovery:** Web Services Discovery protocol scanner. Sends WS-Discovery
+probe messages to detect SOAP/WS-enabled devices on the network.
+
+**024 — TCP SYN Scanner:** Nmap wrapper for half-open (SYN) scanning. Requires Nmap
+installed and root/sudo privileges. Enable with `ENABLE_SYN_SCAN=true`. Faster and
+stealthier than the TCP connect scanner (003).
+
+---
+
+## Discovery Plugins (6)
+
+| ID | Name | Protocol | Purpose |
+|----|------|----------|---------|
+| 025 | DB Scanner | TCP | Database service detection (MySQL, PostgreSQL, Redis, MongoDB, etc.) |
+| 026 | ARP Scanner | ARP | Layer 2 MAC resolution, OUI vendor lookup, OS hints from vendor |
+| 027 | mDNS/Bonjour Scanner | mDNS | Local Bonjour/mDNS service discovery, friendly device names |
+| 028 | UPnP/SSDP Scanner | SSDP | UPnP device discovery via SSDP, description XML parsing |
+| 029 | DNS-SD Scanner | DNS-SD | DNS-based Service Discovery announcements |
+| 030 | LLMNR Scanner | LLMNR | Link-local Multicast Name Resolution (Windows networks) |
+
+### Discovery Plugin Details
+
+**025 — DB Scanner:** Connects to common database ports and fingerprints the service
+from handshake responses. Detects MySQL (3306), PostgreSQL (5432), Redis (6379),
+MongoDB (27017), and others.
+
+**026 — ARP Scanner:** Resolves IP to MAC via ARP request. Performs OUI vendor lookup
+to identify device manufacturer. Vendor name feeds into OS Detector for OS hints
+(e.g., "Apple" → macOS, "Ubiquiti" → Linux).
+
+**027 — mDNS/Bonjour Scanner:** Multicast DNS query for `.local` service announcements.
+Discovers friendly device names, service types (e.g., `_http._tcp`, `_ssh._tcp`),
+and IoT devices broadcasting on the LAN.
+
+**028 — UPnP/SSDP Scanner:** Sends M-SEARCH multicast to discover UPnP devices.
+Parses device description XML for manufacturer, model, firmware version.
+
+**029 — DNS-SD Scanner:** DNS-based Service Discovery. Enumerates `_services._dns-sd._udp`
+zone to find advertised services.
+
+**030 — LLMNR Scanner:** Link-Local Multicast Name Resolution. Detects Windows hosts
+responding to LLMNR queries (useful for Windows network enumeration and detecting
+LLMNR poisoning risk).
+
+---
+
+## Pro Plugins (3)
+
+| ID | Name | Ports | Purpose |
+|----|------|-------|---------|
+| 040 | TLS Certificate & Cipher Auditor | 443, 465, 993, 995, 8443 | Deep TLS audit: cert chain, expiry, weak ciphers, HSTS |
+| 050 | TRIBE v2 Probe | 80, 443 | Detect debug info leaks, stack traces, verbose errors, CORS misconfig |
+| 060 | DNS Security Auditor | 53 | SPF/DKIM/DMARC validation, DNSSEC, zone transfer, MX security, CAA |
+
+### Pro Plugin Details
+
+**040 — TLS Certificate & Cipher Auditor:** Goes beyond the basic TLS Scanner (011)
+with full certificate chain validation, expiration warnings, certificate transparency
+log checks, HSTS header verification, and a comprehensive weak cipher inventory.
+Generates findings for: expired certs, self-signed certs, missing HSTS, weak key
+sizes (<2048-bit RSA), and deprecated cipher suites.
+
+**050 — TRIBE v2 Probe:** Targeted Reconnaissance for Information and Bug Enumeration.
+Sends crafted requests to detect: stack traces in error responses, debug mode
+indicators (`X-Debug`, `X-Powered-By` with version), CORS misconfiguration (wildcard
+origins, credential leaking), verbose error messages, exposed admin panels, directory
+listings, and default pages.
+
+**060 — DNS Security Auditor:** Comprehensive DNS security assessment:
+- **SPF:** Validates Sender Policy Framework record syntax and coverage
+- **DKIM:** Checks for DKIM selector records
+- **DMARC:** Validates DMARC policy (reject/quarantine/none)
+- **DNSSEC:** Checks for DNSSEC signing and validation chain
+- **Zone Transfer (AXFR):** Tests if zone transfer is allowed (security risk)
+- **MX Security:** Validates mail exchange records and TLS support
+- **CAA Records:** Checks Certificate Authority Authorization records
+
+---
+
+## Enterprise Plugins (4)
+
+| ID | Name | Tier | Purpose |
+|----|------|------|---------|
+| 020 | AWS Cloud Scanner | Enterprise | Security group analysis, IAM policy review, S3 bucket checks |
+| 021 | GCP Cloud Scanner | Enterprise | Firewall rule audit, IAM bindings, project-level security |
+| 022 | Azure Cloud Scanner | Enterprise | NSG rule analysis, RBAC review, resource exposure |
+| 023 | Zero Trust Checker | Enterprise | Network segmentation, encryption posture, identity verification scoring |
+
+---
+
+## Execution Order
+
+Plugins run in strict priority order (lower number = runs first):
+
+```
+1. Ping Checker (100)           → Establish basic reachability
+   Host Up Check (110)          → Multi-probe reachability confirmation
+                                          ↓
+2. TCP SYN Scanner (140)        → Half-open port discovery (if Nmap available)
+   Port Scanner (150)           → TCP connect + UDP bulk scan
+                                          ↓
+3. SSH Scanner (200)            → SSH banner + weak algorithms
+   FTP Banner (200)             → FTP daemon + anonymous login
+                                          ↓
+4. HTTP Probe (300)             → Web server headers + tokens
+   SNMP Scanner (300)           → sysDescr + device info
+   DNS Scanner (300)            → version.bind + records
+   NetBIOS/SMB (300)            → NetBIOS names + SMB2 detection
+   SUN RPC (300)                → RPC portmapper enumeration
+   WS-Discovery (300)           → SOAP/WS device discovery
+   TLS Scanner (350)            → TLS versions + cipher suites
+                                          ↓
+5. Webapp Detector (400)        → Technology fingerprinting (Wappalyzer)
+   OpenSearch Scanner (400)     → Elasticsearch/OpenSearch detection
+                                          ↓
+6. OS Detector (99000)          → Fuse all evidence into OS determination
+                                          ↓
+7. Result Concluder (100000)    → Merge all results into final conclusion
+```
+
+**Auto-skip rules:** Plugins with unmet `requirements` are automatically skipped. For
+example, SSH Scanner (requires `tcp_open: [22]`) skips if the Port Scanner didn't find
+port 22 open. This avoids wasted probes and reduces scan time.