SecureGraph AI

1. What is SecureGraph AI?

SecureGraph AI is a GUI-first desktop security platform for developers and AppSec teams. It runs a set of security engines against your codebase and infrastructure, correlates every finding into one security graph, and shows you which issues are actually reachable and exploitable — not just a long, undifferentiated list of alerts. The desktop app is the primary interface; a CLI exists for automation and CI/CD.

2. Core concepts: Scan vs. Observation

Scan is an active check you run on demand (or in CI). It executes one or more engines against your codebase or artifact and produces raw findings for that run.

Observation is what SecureGraph AI builds from your scans over time — the Security Graph and everything layered on it (Correlation, Attack Paths, the risk score, the Living Threat Model). It links findings across engines onto your real application structure and tracks how your risk posture changes scan over scan.

3. The engines — what each one does

4. Before your first scan: engine dependencies

Most engines above drive a separate command-line tool that has to be installed on your machine first — SecureGraph AI does not silently bundle or auto-install these (Taint Analysis is the one exception; it's fully built in). If you run a scan before its tool is installed, that engine's result shows an error like "<tool> binary not usable on PATH: ..." instead of findings — the other engines you do have installed still run normally.

Full install commands and a troubleshooting table are in the Admin Guide below. Settings → Scanner Tool Locations shows exactly which path the app found for each tool, with an Auto-detect button.

5. Running a scan — how to

1. Open SecureGraph AI and select or add your project/repository.
2. Go to Scan and choose scope: full workspace, a specific path, or a specific engine subset.
3. Click Run Scan. Progress and per-engine status show live.
4. When complete, findings land in the Findings view, deduplicated and enriched with CWE/CVE metadata.

Command-line equivalent (CI/automation): the securegraph CLI supports the same scope flags and report fields as the GUI.

6. The Security Graph, Correlation & Attack Paths

• Security Graph — a navigable graph of your application's components, data flows, and findings.
• Correlation — groups findings that share a root cause or are duplicates reported by different engines.
• Attack Paths — chains correlated findings into candidate exploit paths.

7. Dashboards — which one is for whom

8. Findings & their lifecycle

Each finding carries severity, CWE/CVE identifiers where applicable, exact file/line location (or an honest "not provided by <scanner>" label), and remediation guidance. Findings have an explicit lifecycle (open, triaged, resolved) that persists across re-scans. Secret validation can optionally live-check whether a discovered credential is actually active, opt-in per provider.

9. Reports — the ten report types

Export formats: HTML (print-ready CSS), JSON, CSV, SARIF, CycloneDX, and SPDX.

10. Reading a report — conventions to know

• "Not provided by <scanner>" — the underlying engine genuinely didn't report that field. Not an error.
• "Stale" — an open critical/high finding still open more than 30 days after first detection.
• Application security score — 100, minus 18 pts/open critical, minus 7 pts/open high, minus up to 20 pts total for everything else, floored at 0.
• Score bands — Strong 90–100, Managed 75–89, Needs attention 60–74, High risk below 60.

11. What to expect

• First scan on a large codebase takes longer; subsequent scans are faster due to caching.
• Not every finding is exploitable — use Correlation/Attack Paths to prioritize.
• Your source code is not silently sent to external AI providers by default.
• Registering is free and optional; it unlocks governance-dashboard extras only.

12. Installation & licensing

• Desktop Community edition: single binary/installer (MSI and NSIS), one edition, binary registered/unregistered state.
• Registration (Settings → License → Register) is free, non-expiring, email only — sends email + a one-way device fingerprint to api.vaultmorph.org.
• Registration unlocks governance-dashboard extras only — scanning, reports, exports all work unregistered.
• Uninstalling: Start Menu or Control Panel both call the same uninstaller. Per-user app data is not removed on uninstall by design. A locked running process is the most common cause of a silent NSIS uninstall failure.

13. Installing the scanner engines & their dependencies

SecureGraph AI itself is one self-contained installer, but most scan engines drive a separate external command-line tool that has to be installed on the machine independently — the app does not silently bundle or auto-install these (Taint Analysis is the one exception, fully built in). This is the most common source of first-setup confusion — start with the quick-reference table to find exactly where each tool's path is configured, then follow the per-tool steps below it.

Quick reference — where does each path go?

If a row shows blank/not-found in Settings after installing, that tool did not land on your system PATH — normal for manual downloads. Paste the full path to the .exe into the matching field and it resolves immediately, no restart needed.

Semgrep (SAST — primary engine)

1. Install Python 3 from python.org/downloads — tick "Add python.exe to PATH" on the first setup screen. Skip if Python is already installed.
2. Open PowerShell or Command Prompt: pip install semgrep
3. Verify: semgrep --version should print a version number.
4. Usually no further step — Settings → Scanner Tool Locations → Auto-detect finds pip-installed tools via Python itself, not just PATH.

Checkov (IaC Security)

Same pattern as Semgrep: pip install checkov, verify with checkov --version, Auto-detect finds it the same way.

OSV-Scanner (SCA / Dependencies)

• Recommended: winget install --id Google.OSVScanner -e
• Fallback (no winget, or air-gapped): download the Windows binary from github.com/google/osv-scanner/releases and keep it somewhere permanent, e.g. C:\Tools\osv-scanner\osv-scanner.exe.
• Verify: osv-scanner --version
• winget installs resolve on PATH automatically; manual downloads need the full path pasted into Settings → Scanner Tool Locations → OSV-Scanner.
• Run the one-time database bootstrap below before your first real scan.

Gitleaks (Secrets Scanning)

• Recommended: winget install --id Gitleaks.Gitleaks -e
• Fallback: download gitleaks_<version>_windows_x64.zip from github.com/gitleaks/gitleaks/releases, extract it, keep gitleaks.exe somewhere permanent.
• Verify: gitleaks version
• Set the path in Settings → Scanner Tool Locations → Gitleaks if it isn't found automatically.

Trivy (Container Security)

• Recommended: winget install --id AquaSecurity.Trivy -e
• Fallback: download trivy_<version>_windows-64bit.zip from github.com/aquasecurity/trivy/releases, unzip, keep trivy.exe somewhere permanent.
• Verify: trivy --version
• Set the path in Settings if needed, then run the one-time database bootstrap below.

OpenGrep (SAST — second engine)

• No winget or pip package exists — download opengrep_windows_x86.exe directly from github.com/opengrep/opengrep/releases and move it somewhere permanent, e.g. C:\Tools\opengrep\opengrep.exe.
• Windows SmartScreen will very likely warn on first run of a freshly downloaded .exe — click "More info" then "Run anyway" only after confirming the download came from the official opengrep/opengrep GitHub repo.
• Verify: run it once from its folder — .\opengrep.exe --version
• Because OpenGrep is never Python-auto-detected and rarely lands on PATH, you will almost always need to paste its exact path into Settings → Scanner Tool Locations → OpenGrep — this is expected, not a sign something is broken.

OWASP ZAP (DAST)

• Recommended: winget install --id ZAP.ZAP -e
• Fallback: download the Windows installer from zaproxy.org/download and run it.
• Some ZAP versions bundle their own Java runtime, some need a separate JRE — check the download page for the version you're installing.
• Known false positive: some ZAP installer builds have been flagged by Microsoft Defender/SmartScreen (tracked upstream as zaproxy/zaproxy#8491). Confirm the download came from zaproxy.org and check the file hash on the download page before proceeding.
• After install, point Settings → Scanner Tool Locations → ZAP at it if not found automatically (the DAST screen also has its own Auto-detect for ZAP specifically).

General Windows install notes

• Admin rights: pip installs use --user and need no admin rights. winget can install per-user or machine-wide; manual downloads need no admin rights either as long as you can write to where you put the binary.
• "winget" not recognized: it ships as the "App Installer" component, preinstalled on most current Windows 10/11 machines. If your terminal doesn't recognize it, install "App Installer" from the Microsoft Store, or use the manual-download fallback.
• SmartScreen warnings are expected, not necessarily a red flag: most of these are open-source CLI tools without a paid code-signing certificate, so a freshly downloaded .exe/.zip from GitHub Releases routinely triggers "Windows protected your PC." Confirm the URL is the project's official GitHub repo before clicking through.
• Corporate network/proxy: winget, pip, and GitHub downloads all need outbound HTTPS. If your organization blocks these, download the binaries on a machine that does have access and copy them over, then set the explicit path for each in Settings.

One-time database bootstrap (OSV-Scanner & Trivy)

Both need a local vulnerability database before their first real scan — separate from installing the binary, and the one network-touching step in an otherwise offline pipeline. OSV-Scanner: osv-scanner scan source --offline-vulnerabilities --download-offline-databases -r <dir> with OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY set to your cache location. Trivy: trivy image --download-db-only --cache-dir <dir>. Settings shows a DB status panel for both (with the exact command shown next to each), flags staleness after 14 days (advisory only, never blocks a scan), and has a "Download/Update DB now" button (capped at 15 minutes) that runs it for you.

Verifying everything worked

• Settings → Scanner Tool Locations shows, per tool: any override you've set, the path the app actually resolved, and whether it fell through to the bare-PATH fallback (worth fixing with an explicit path if so — see Troubleshooting below).
• The most reliable end-to-end check: enable every engine and run one scan. Each engine should report findings (or "no findings") rather than a "binary not usable on PATH" error.

How the app finds each tool (resolution order)

1. An explicit path set in Settings → Scanner Tool Locations, if configured.
2. For Semgrep/Checkov only: the app asks Python where it puts console scripts (the Auto-detect button) — never automatic.
3. The bare tool name on your system PATH — today's fallback.

A Repair button (Semgrep/Checkov only) runs pip install --force-reinstall --user <tool> (capped at 6 minutes) and needs Python on PATH.

14. Configuring scans

• Engine selection/scope: Settings → Scan Engines, per project.
• CI/CD: the securegraph CLI mirrors the GUI's scope flags and report fields.
• Custom SAST rules via Rule Management: enable/disable, pin, roll back, import/export.

15. Troubleshooting scan/engine failures

16. AI Context Firewall & AI Audit

• Local-only mode is the default — nothing leaves the machine unless you enable an external provider.
• Providers: OpenAI, Anthropic, generic OpenAI-compatible/local LLM, or a CLI provider (which itself typically calls a remote cloud API under its own credentials).
• AI Audit Engine mode: 0 = metadata only, 1 = security context, 2 = full sanitized content.

17. Secrets validation policy

Opt in, per provider, to live-validate a discovered credential. Off by default; enabling discloses exactly where the check is sent.

18. Reports — admin-level notes

• HTML reports use print-ready CSS — use your browser's Print to PDF.
• Report branding (logo, etc.) is a persisted default set in Settings.
• The score formula/bands and the 30-day Stale threshold are documented in each report's own Definitions section.

19. Privacy & consent

A first-run, non-dismissible Privacy Notice must be accepted before registration is possible. See the full Privacy Policy (GDPR, India DPDP Act 2023, CCPA).

20. SIEM integration & Enterprise deployment

SIEM Integration streams findings/events to an external SIEM. Enterprise Deployment covers multi-seat/organization settings, separate from free Desktop Community registration.

21. Data & storage

Findings, scan history, and the graph are stored locally in SQLite. SBOM/CBOM exports follow CycloneDX 1.6. Config file: <config_dir>\securegraph.toml.

22. Support

Product homepage: vaultmorph.org. License/registration issues: api.vaultmorph.org admin tooling. Privacy requests: contact@vaultmorph.org.