sys-scan-agent 5.0.3.dev0

AI-powered intelligence layer for the sys-scan-graph security scanner.

╔══════════════════════════════════╗ ║ MazzLabs ║ ╟──────────────────────────────────╢ ║ Joseph Mazzini ║ ╚══════════════════════════════════╝

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.

It combines a high-performance C++20 scanning engine with a Python-based intelligence layer featuring an embedded, fine-tuned Mistral-7B LLM with LoRA adapters. The core engine uses modern dependency injection patterns and type-safe enums to gather security data across 16 specialized scanners, outputting canonical JSON, NDJSON, SARIF, or HTML. The intelligence layer uses LangGraph state machines for cyclical reasoning, baseline learning via SQLite, and 32-dimensional process embeddings for novelty detection—all running locally with zero external API calls.

Key Features

• Blazing-fast scanning built in C++20 with deterministic, reproducible results
• Zero-trust AI intelligence powered by embedded fine-tuned Mistral-7B with LoRA adapters (NO external APIs)
• 16 specialized scanners covering processes, network, kernel modules, SUID/SGID, IOC detection, and compliance
• Multiple output formats including canonical JSON, NDJSON, SARIF, and self-contained HTML
• LangGraph-orchestrated analysis with cyclical reasoning and baseline learning
• Risk scoring and compliance with PCI DSS, HIPAA, and NIST CSF assessment
• Fleet-wide rarity analysis using SQLite baseline database with process novelty detection
• MITRE ATT&CK integration with native technique mapping and coverage analysis

---

Quick Start

Installation

Option 1: Install from Debian Package (Recommended)

# Add the Mazzlabs repository
echo "deb [signed-by=/etc/apt/trusted.gpg.d/mazzlabs-archive-keyring.gpg] https://apt.mazzlabs.works testing main" | sudo tee /etc/apt/sources.list.d/mazzlabs.list

# Import the GPG key
curl -fsSL https://apt.mazzlabs.works/mazzlabs-archive-keyring.gpg | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/mazzlabs-archive-keyring.gpg > /dev/null

# Verify the key fingerprint (optional but recommended)
gpg --show-keys /etc/apt/trusted.gpg.d/mazzlabs-archive-keyring.gpg

# Update package lists and install
sudo apt update
sudo apt install sys-scan-graph

Option 2: Build from Source

# Clone the repository
git clone https://github.com/J-mazz/sys-scan-graph.git
cd sys-scan-graph

# Build the core scanner
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

# Install Python dependencies for intelligence layer
cd agent
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

Basic Usage

Using Installed Package

# Run a basic scan with canonical JSON output
sys-scan --canonical --output report.json

# Run with intelligence layer for AI-powered analysis
sys-scan-graph analyze --report report.json --out enriched_report.json

# Generate HTML report with visualizations
sys-scan-graph analyze --report report.json --out enriched_report.json --prev baseline.json

Using Source Build

# Run a basic scan with canonical JSON output
./build/sys-scan --canonical --output report.json

# Run with intelligence layer for AI-powered analysis
cd agent
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_v2.json --prev 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-based 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 C++20 enums and dependency injection via ScanContext
• Deterministic, reproducible results with canonical JSON (RFC 8785 JCS) and stable ordering
• Zero-trust security with embedded LLM, capability dropping, and seccomp sandboxing
• Thread-safe parallelization with mutex-protected report aggregation
• Extensible plugin system supporting custom scanners, rules, and LLM providers
• Comprehensive testing with 919 test cases (698 C++, 221 Python)

---

Licensing

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

---

Support & Community

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

---