NetGuard User Guide

v0.1 — from install to your first compliance binder.

1. Install

NetGuard ships as a single binary per platform, distributed inside a .zip wrapper. The zip exists to bypass Chrome / Edge's "uncommonly downloaded file" warning on the bare .exe; once you extract, the binary inside is the same single-file PyInstaller bundle.

Windows install — step by step

1. Download netguard-0.1-windows-x64.zip.
2. Right-click the zip → Extract All… → choose a destination folder.
3. In the extracted folder, right-click netguard-0.1-windows-x64.exe → Properties → at the bottom of the General tab, tick Unblock → OK. (This clears the Mark-of-the-Web flag Windows added during download.)
4. Double-click the .exe. Windows SmartScreen will show "Windows protected your PC" the first time. Click More info, then Run anyway.
5. NetGuard opens in its own desktop window. CLI mode: open CMD or PowerShell in the same folder and run netguard-0.1-windows-x64.exe --audit foo.cfg --ckl-out report.ckl.

macOS install — step by step

1. Download netguard-0.1-macos-arm64.zip.
2. Double-click the zip to extract.
3. Move netguard-0.1-macos-arm64 to /Applications or anywhere on your PATH.
4. The first time you run it, macOS Gatekeeper will block ("cannot be opened because Apple cannot check it for malicious software"). Open System Settings → Privacy & Security → scroll to the netguard entry → click Open Anyway.
5. From terminal: chmod +x netguard-0.1-macos-arm64 && ./netguard-0.1-macos-arm64 --app

2. First run

Launch the desktop app:

# Desktop window (recommended)
netguard --app

# Or as a Flask UI in your default browser
netguard

# Or one-shot CLI audit
netguard --audit /path/to/running-config.cfg --ckl-out report.ckl

The first launch builds the STIG catalog from the bundled DISA quarterly XCCDFs (~15 seconds). After that, audits run in < 1 second per device.

3. Single-device audit

1. Open the netguard window.
2. Paste a Cisco running-config into the textarea — or click "Upload" and select a single .cfg file.
3. Click Run audit.
4. The findings page renders with summary stats, FAILs (with Deviation block), MANUAL items triaged into Likely-N/A / Applicable / General review.

4. Batch audit

Same form, but select multiple files via the upload field (hold Shift / Ctrl while picking). When ≥ 2 files are uploaded, netguard redirects to the batch dashboard:

• Aggregate stats across the batch (total PASS / FAIL / MANUAL, plus triage bucket totals)
• Per-device row with hostname, product, individual counts, "Details →" drilldown
• One-click ZIP downloads: all CKLs, all annotated configs, all XLSX, plus a combined CSV

5. Live SSH-pull

From the index page, click ⚡ SSH-pull a live device. Fill in:

• Host: device IP or DNS name
• Username: typically a dedicated scan account with privilege-15 read-only
• Password: scan account passcode (RSA-token logins are not supported here — use the fixed-passcode pattern)
• Enable secret (optional): only needed if the scan user requires enable to reach exec mode
• Device type: leave on Auto-detect unless you know the platform

NetGuard SSHs to the device, pulls show running-config + show version + show inventory, parses the facts (hostname, model, software, serial, uptime), and runs the full audit pipeline. The Findings page links to the standard set of artifact downloads.

6. Output artifacts

7. Reading the findings

FAIL — Deviation engine

Every FAIL shows four structured fields:

Expected: exec-timeout ≤ 5 minutes (≤ 300 seconds)
Actual:   line vty 0 4 → exec-timeout 9 59 (599s)
At:       line vty 0 4 (line 291)
Patch:
  line vty 0 4
   exec-timeout 5 0

The Patch block contains the exact config commands to paste. Source-line refs let you navigate directly to the offending stanza.

MANUAL — Triage buckets

• Likely Not Applicable — netguard's 25-topic classifier matched the rule against a feature the device doesn't have. Example: a BGP rule on a device that runs no BGP. Admin still confirms; we recommend but don't decide N/A.
• Applicable, review localized — the rule's feature is present on the device. NetGuard points at the relevant config region (e.g., "router eigrp 100, lines 166–173").
• General review — no topic match. Standard manual review required.

8. Catalog refresh

Each DISA quarterly cycle, drop the new XCCDF zip into the 📚 Catalog refresh page (linked from the index). NetGuard extracts safely under stigs/ (zip-slip protected) and rebuilds the in-process catalog. No service restart required.

9. History & drift

Every config you submit (paste / upload / SSH-pull) is saved under ~/.netguard/configs/ with a sidecar metadata JSON. Open 🗂 Audit history to see them all, newest-first.

Re-audit → reruns the saved config against the current catalog — useful after a quarterly STIG release.

Compare 2 selected → diffs two saved audits: NEW FAILs, RESOLVED items, status changes. Drift detection in one click.

10. CLI reference

# Audit a single config
netguard --audit foo.cfg [--ckl-out X --annotate-out Y --xlsx-out Z]

# Live device, end-to-end
netguard --pull HOST --user scan --audit-after [--out-dir ./pulls/]
  # Produces in ./pulls/:
  #   <host>-<stamp>.cfg
  #   <host>-<stamp>.metadata.json
  #   <host>-<stamp>.annotated.cfg
  #   <host>-<stamp>.ckl
  #   <host>-<stamp>.xlsx

# Build / refresh the STIG catalog
netguard --build-stig-catalog stigs --catalog-out stigs/stig_catalog.json

# Launch the GUI
netguard --app                  # native desktop window
netguard                        # Flask + auto-opens browser
netguard --no-browser           # Flask only (headless / remote-viewing)

11. Compliance binder workflow

1. Pull or upload all in-scope devices. Batch mode is fastest for ≥ 5 devices.
2. Download every .ckl. Open in DISA STIG Viewer. Flip every "MANUAL · Likely N/A" item to NOT_APPLICABLE after confirming netguard's reasoning.
3. Address FAILs. The Deviation block has the exact patch; coordinate the change with the device's owner via your change-management process.
4. Print the PDF for the executive summary, paste the annotated .cfg into the technical binder, and attach the .xlsx for the analyst's working notes.
5. Save the audit. The config is already persisted under ~/.netguard/configs/; nothing more to do. Re-audit after the quarterly STIG cycle or after any device config change.

12. Operating posture

• Binds to 127.0.0.1 by default. Configs are processed in-process; nothing is sent over the network.
• The only outbound traffic is SSH to operator-specified device IPs via --pull. Pass --no-browser or run only the CLI for fully-offline scripted use.
• Credentials (SSH password, enable secret) live in memory for the duration of the pull; never written to disk.
• Audit configs are saved in plaintext under ~/.netguard/configs/. No encryption-at-rest in v0.1 — consult your IA posture if this needs to change.
• No telemetry. No phone-home. No update checks. No external LLM. No model downloads.

13. Troubleshooting

"No catalog loaded"

NetGuard couldn't find the STIG catalog. Build it: netguard --build-stig-catalog stigs --catalog-out stigs/stig_catalog.json. Or import via the /catalog page in the UI.

SSH-pull times out

Confirm reachability: ssh scan@HOST from a terminal. If interactive SSH works but netguard fails, try --device-type cisco_xe (or your platform) instead of auto.

Native window doesn't open on Linux

WebKitGtk required: sudo apt install python3-gi gir1.2-webkit2-4.0. NetGuard auto-falls-back to your default browser if no webview backend is present.

"Address already in use"

Another netguard process is running. Find it (pgrep -fa netguard) and kill it, or pass --port 9998 to use an alternate port.

Where are the diagnostic logs?

/status page in the UI shows catalog state, registered checks, in-memory and persisted audit counts. For deeper diagnostics, run with --debug (coming in v0.2).