sys-scan-graph

System Security Scanner & Intelligence Graph

Sys-Scan-Graph is a high-speed security analysis tool that transforms raw data from multiple security surfaces into a unified, actionable report.

This directory contains the optional Python intelligence layer, published as the sys-scan-agent package. It consumes JSON produced by the C++ core scanner and enriches/summarizes results locally.

Key Features

• Local-first analysis of sys-scan JSON reports
• CLI entry points provided by the package (sys-scan-graph, sys-scan-intelligence)
• Deterministic outputs via canonicalization and stable ordering
• Optional artifacts such as HTML reports (configured via config.yaml) and metrics export (--metrics-out)

Quick Start

Installation

The intelligence layer is installed separately from the C++ core.

python3 -m venv .venv
source .venv/bin/activate

pip install -U pip
pip install sys-scan-agent

Optional local-LLM dependencies:

pip install \
  langgraph langchain-core \
  torch transformers peft accelerate safetensors huggingface_hub

Optional external inference dependencies (LangChain API provider):

# IMPORTANT: You must provide your own provider credentials (not bundled with this project).
pip install langchain langchain-openai langchain-anthropic

Basic Usage

# Run the C++ core scanner (from the repo root)
./build/sys-scan --canonical --output report.json

# Analyze/enrich with the Python layer
source .venv/bin/activate
sys-scan-graph analyze --report report.json --out enriched_report.json

Generate HTML Report

# Enable HTML generation in ./config.yaml, then run:
sys-scan-graph analyze --report report.json --out enriched_report.json

Documentation

For detailed documentation, see our comprehensive wiki:

• Architecture Overview - High-level system architecture, core vs intelligence layer responsibilities
• Core Scanners - Scanner implementations, signals, output formats, and schemas
• Intelligence Layer - Pipeline stages, LangGraph orchestration, LLM providers, data governance

Additional Resources

• Rules Engine - Rule file formats, MITRE aggregation, severity overrides, validation
• CLI Guide - Complete command reference
• Extensibility - Adding custom scanners and rules

Repository Structure

This repository contains:

• Core Scanner (src/, CMakeLists.txt) - High-performance C++ scanning engine
• Intelligence Layer (agent/) - Python package (sys-scan-agent) for analysis and enrichment
• Rules (rules/) - Security rules and MITRE ATT&CK mappings
• Documentation (docs/wiki/) - Comprehensive project documentation
• Tests (tests/, agent/tests/) - Test suites for both components

Key Design Principles

• Type-safe architecture with a C++23 toolchain using C++20 modules and dependency injection via ScanContext
• Deterministic, reproducible results with stable ordering and canonicalization in the Python layer
• Local-first security posture: no outbound LLM API calls by default; optional external inference is explicit opt-in
• Thread-safe parallelization with mutex-protected report aggregation
• Extensible plugin system supporting custom scanners, rules, and LLM providers
• Comprehensive testing via CTest (C++) and pytest (Python)

Licensing

This project is licensed under the Apache License 2.0. See LICENSE for complete licensing details.

Support & Community

• Documentation: Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: See SECURITY.md for vulnerability disclosure