Metadata-Version: 2.4
Name: sys-scan-agent
Version: 7.0.0
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 Mazzini <joseph@mazzlabs.works>
Maintainer-email: Joseph Mazzini <joseph@mazzlabs.works>
License: Apache License 2.0
Project-URL: Homepage, https://github.com/J-mazz/sys-scan-graph
Project-URL: Repository, https://github.com/J-mazz/sys-scan-graph
Project-URL: Issues, https://github.com/J-mazz/sys-scan-graph/issues
Project-URL: Documentation, https://github.com/J-mazz/sys-scan-graph#readme
Keywords: security,scanner,ai,intelligence,analysis
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: System :: Monitoring
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: PyNaCl<2,>=1.5
Requires-Dist: huggingface_hub>=0.20.0
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: llama-cpp-python>=0.2.26; extra == "ai"
Provides-Extra: api
Requires-Dist: langchain<1,>=0.3; extra == "api"
Requires-Dist: langchain-core<1,>=0.3; extra == "api"
Requires-Dist: langchain-openai<1,>=0.2; extra == "api"
Requires-Dist: langchain-anthropic<1,>=0.2; extra == "api"
Provides-Extra: dev
Requires-Dist: pytest<9,>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio<0.24,>=0.23; extra == "dev"
Requires-Dist: black<24,>=23.0; extra == "dev"
Requires-Dist: isort<6,>=5.12; extra == "dev"
Requires-Dist: mypy<2,>=1.5; extra == "dev"
Requires-Dist: flake8<7,>=6.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# sys-scan-graph

![sys-scan-graph Logo](../assets/sys-scan-graph_badge.jpg)

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

[![CodeScene Analysis](https://codescene.io/images/analyzed-by-codescene-badge.svg)](https://codescene.io/projects/75070)
[![CodeScene Average Code Health](https://codescene.io/projects/71206/status-badges/average-code-health)](https://codescene.io/projects/75070)
[![CodeScene System Mastery](https://codescene.io/projects/71206/status-badges/system-mastery)](https://codescene.io/projects/75070)

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.

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

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

Optional local-LLM dependencies:

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

Optional external inference dependencies (LangChain API provider):

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

### Basic Usage

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

```bash
# 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](../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 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`](../LICENSE) for complete licensing details.

---

## Support & Community

- **Documentation**: [Wiki](../docs/wiki/_index.md)
- **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

---

![Mazzlabs Logo](../assets/Mazzlabs.png)

