Metadata-Version: 2.4
Name: antguard
Version: 0.1.0
Summary: Guard. Detect. Protect. Pure system-level profiler for AI data privacy.
Author: VK-Ant (Venkatkumar Rajan)
License: Apache-2.0
Project-URL: Homepage, https://github.com/VK-Ant/antguard
Project-URL: Repository, https://github.com/VK-Ant/antguard
Project-URL: Issues, https://github.com/VK-Ant/antguard/issues
Keywords: ai-security,data-privacy,runtime-monitoring,profiler,audit,exfiltration-detection,file-monitoring,network-monitoring
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: watchdog>=3.0
Requires-Dist: psutil>=5.9
Provides-Extra: gpu
Requires-Dist: pynvml>=11.0; extra == "gpu"
Provides-Extra: all
Requires-Dist: pynvml>=11.0; extra == "all"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/VK-Ant/antguard/main/assets/antguard.png" alt="antguard" width="800"/>
</p>

<p align="center">
  <strong>Guard, Detect, Protect.</strong><br>
  Pure system-level profiler for AI data privacy. Like <code>cProfile</code>, but for data movement.
</p>

<p align="center">

  <a href="https://pypi.org/project/antguard/"><img src="https://img.shields.io/badge/PyPI-v0.3.1-green" alt="PyPI"></a>

  <a href="https://github.com/VK-Ant/antguard/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License"></a>
  <a href="https://colab.research.google.com/github/VK-Ant/antguard/blob/main/demo/antguard_quickstart.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"></a>
</p>

No AI, No API, No cloud, No regex, Works offline, Works air-gapped.

## Install

```bash
pip install antguard
```

For NVIDIA GPU monitoring:
```bash
pip install antguard[gpu]
```

## Quick Start

```python
from antguard import Guard

# Context manager (recommended)
with Guard(watch=["./data/"]) as g:
    # your code runs here - completely unchanged
    agent.run("process confidential.pdf")

# The one answer that matters
print(g.did_data_leave())  # True or False

# Save reports
g.save("./logs/")  # creates .log + .txt + .json
```

## What It Monitors

| Layer | What | How |
|-------|------|-----|
| **File** | Every read, write, copy, move, delete | watchdog + SHA256 fingerprinting |
| **Network** | Every outbound connection, bytes sent | psutil network polling |
| **Process** | Process creation, shell commands, suspicious binaries | psutil process tree |
| **Correlation** | Match file bytes to outbound network data | Chunk hash + size + temporal |
| **Runtime** | CPU, GPU, memory, disk I/O | psutil + pynvml (optional) |

## How It Works

<p align="center">
  <img src="https://raw.githubusercontent.com/VK-Ant/antguard/main/assets/arch.png" alt="arc" width="100%">
</p>

antguard wraps your code from the outside. It never reads file contents.
It tracks data flow by fingerprinting files and correlating byte movement.

## API

```python
from antguard import Guard

guard = Guard(
    watch=["./data/"],           # directories to monitor
    detect_outbound=True,        # network monitoring
    track_processes=True,        # process tree monitoring
    correlate=True,              # byte-flow correlation
    runtime=True,                # CPU/GPU/memory metrics
    gpu=True,                    # GPU monitoring
    log_path="./logs/",          # log output directory
)

guard.start()
# ... your code ...
guard.stop()

# Query results
guard.did_data_leave()       # bool
guard.file_events()          # list of file events
guard.net_events()           # list of network events
guard.proc_events()          # list of process events
guard.correlations()         # file-to-network matches
guard.matched_files()        # files found in outbound data
guard.runtime_metrics()      # CPU, GPU, memory summary
guard.risk_level()           # LOW / MEDIUM / HIGH / CRITICAL
guard.anomalies()            # runtime anomalies
guard.data_flow_map()        # full byte flow visualization
guard.save("./logs/")        # write reports
guard.summary()              # one-line summary
```

## Report Output

**Text report** (`antguard_report_*.txt`):
```
antguard Profiler Report
==================================================
Session    : a1b2c3d4
Platform   : Linux (6.5.0)
Duration   : 12.3 seconds

DATA LEFT SYSTEM: NO

-- FILE EVENTS (2) --
  [MODIFY  ] ./data/salary.pdf  240.0 KB  python(pid 4521)  LOW
  [CREATE  ] ./output/summary.txt  1.0 KB  python(pid 4521)  LOW

-- NETWORK EVENTS (0) --
  None

-- PROCESS EVENTS (3 total, 0 suspicious) --
  All processes normal

-- BYTE-FLOW CORRELATIONS (0) --
  No file-to-network correlations detected

-- RUNTIME METRICS (12 samples) --
  CPU avg/peak    : 35.2% / 72.1%
  Memory avg/peak : 8.2 GB / 8.5 GB
  Process RSS     : 156.0 MB avg, 189.0 MB peak
  GPU             : not detected

==================================================
OVERALL RISK: LOW
==================================================
```

## Cross-Platform

| Component | Windows | Linux | macOS |
|-----------|---------|-------|-------|
| File monitoring | ReadDirectoryChangesW | inotify | FSEvents |
| Network monitoring | WMI | /proc/net | lsof |
| Process monitoring | Windows API | /proc | sysctl |
| GPU (NVIDIA) | pynvml | pynvml | N/A |
| CPU/Memory | psutil | psutil | psutil |

## Demos

| Demo | What it shows |
|------|--------------|
| [Full Audit](demo/demo_05_full_audit.py) | All features combined — the showcase demo |
| [Exfiltration Detection](demo/demo_02_exfiltration_detection.py) | Catches data sent to external server |
| [File Monitoring](demo/demo_01_file_monitoring.py) | File tracking + SHA256 fingerprinting |
| [Suspicious Process](demo/demo_03_suspicious_process.py) | Shell and subprocess detection |
| [Runtime Metrics](demo/demo_04_runtime_metrics.py) | CPU, GPU, memory profiling |
| [Wrap Any Library](demo/demo_06_wrap_any_library.py) | Zero code changes — cProfile pattern |

**Google Colab:** [Open quickstart notebook](https://colab.research.google.com/github/VK-Ant/antguard/blob/main/demo/antguard_quickstart.ipynb)

## Dependencies

Core: `watchdog` + `psutil` (that's it)

Optional: `pynvml` (NVIDIA GPU metrics)

## Memory Footprint

< 25 MB RAM regardless of session length. Events stream to disk.

## Part of the Ant Intelligence Ecosystem

- **antguard** - Guard. Detect. Protect. (system profiler)
- **llmevalkit** - Evaluate. Score. Improve. (AI evaluation)
- Together: full AI system audit

## License

Apache 2.0

## Author

**Venkatkumar Rajan**
