Metadata-Version: 2.4
Name: sys-scan-agent
Version: 5.0.3.dev0
Summary: AI-powered intelligence layer for the sys-scan-graph security scanner.
Home-page: https://github.com/J-mazz/sys-scan-graph
Author: Joseph Mazzini
Author-email: joseph@mazzlabs.works
License: Apache License 2.0
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Security
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: sqlalchemy<3,>=2.0
Requires-Dist: typer<0.13,>=0.12
Requires-Dist: rich<14,>=13.0
Requires-Dist: click<8.2.0,>=8.1.0
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: orjson<4,>=3.9
Requires-Dist: jsonschema<5,>=4.21
Requires-Dist: pytest<9,>=8.0
Requires-Dist: pytest-asyncio<0.24,>=0.23
Requires-Dist: PyNaCl<2,>=1.5
Provides-Extra: ai
Requires-Dist: langgraph<1,>=0.2; extra == "ai"
Requires-Dist: langchain-core<1,>=0.3; extra == "ai"
Requires-Dist: torch>=2.0.0; extra == "ai"
Requires-Dist: transformers>=4.40.0; extra == "ai"
Requires-Dist: peft>=0.10.0; extra == "ai"
Requires-Dist: accelerate>=0.29.0; extra == "ai"
Requires-Dist: safetensors>=0.4.0; extra == "ai"
Requires-Dist: huggingface_hub>=0.20.0; extra == "ai"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

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

# sys-scan-graph

<div align="center">
  <img src="assets/sys-scan-graph_badge.jpg" alt="sys-scan-graph Logo" width="500"/>
</div>

## 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.

<div align="center">
  <a href="https://codescene.io/projects/71206">
    <img src="https://codescene.io/images/analyzed-by-codescene-badge.svg" alt="CodeScene Analysis" />
  </a>
  <a href="https://codescene.io/projects/71206">
    <img src="https://codescene.io/projects/71206/status-badges/average-code-health" alt="CodeScene Average Code Health" />
  </a>
  <a href="https://codescene.io/projects/71206">
    <img src="https://codescene.io/projects/71206/status-badges/system-mastery" alt="CodeScene System Mastery" />
  </a>
</div>

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)

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](docs/wiki/_index.md):

- **[Architecture Overview](docs/wiki/Architecture.md)** - High-level system architecture, core vs intelligence layer responsibilities
- **[Core Scanners](docs/wiki/Core-Scanners.md)** - Scanner implementations, signals, output formats, and schemas
- **[Intelligence Layer](docs/wiki/Intelligence-Layer.md)** - Pipeline stages, LangGraph orchestration, LLM providers, data governance

### Additional Resources

- **[Rules Engine](docs/wiki/Rules-Engine.md)** - Rule file formats, MITRE aggregation, severity overrides, validation
- **[CLI Guide](docs/wiki/CLI-Guide.md)** - Complete command reference
- **[Extensibility](docs/wiki/Extensibility.md)** - 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`](LICENSE) for complete licensing details.

---

## Support & Community

- **Documentation**: [Wiki](docs/wiki/_index.md) | [GitHub Wiki](https://github.com/J-mazz/sys-scan-graph/wiki)
- **Issues**: [GitHub Issues](https://github.com/J-mazz/sys-scan-graph/issues)
- **Discussions**: [GitHub Discussions](https://github.com/J-mazz/sys-scan-graph/discussions)
- **Security**: See [`SECURITY.md`](SECURITY.md) for vulnerability disclosure

---

<div align="center">
  <img src="assets/Mazzlabs.png" alt="Mazzlabs Logo" width="200"/>
</div>
