Metadata-Version: 2.4
Name: antguard
Version: 0.2.0
Summary: Guard, Detect, Protect. Pure system-level profiler for AI data privacy.
Author: 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: policy
Requires-Dist: pyyaml>=6.0; extra == "policy"
Provides-Extra: llmevalkit
Requires-Dist: llmevalkit; extra == "llmevalkit"
Provides-Extra: all
Requires-Dist: pynvml>=11.0; extra == "all"
Requires-Dist: pyyaml>=6.0; extra == "all"
Requires-Dist: llmevalkit; 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-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>

<p align="center">No AI, No API, No cloud, No regex, Works offline, Works air-gapped.</p>

## Install

```bash
pip install antguard
```

Optional extras:
```bash
pip install antguard[gpu]          # NVIDIA GPU monitoring
pip install antguard[policy]       # YAML policy files
pip install antguard[llmevalkit]   # combined report bridge
pip install antguard[all]          # everything
```

## 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) |
| **Policy** | Enforce file/network/process rules | Declarative YAML or dict |
| **Observer** | Detect calls to known service endpoints | Network destination matching |
| **Bridge** | Combined antguard + llmevalkit report | Optional unified audit |

## 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, Policy

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
    policy=Policy({...}),        # security rules (optional)
    observe_endpoints=True,      # endpoint detection (optional)
    log_path="./logs/",          # log output directory
)

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

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

# Policy
guard.policy_violations()    # list of rule violations
guard.generate_baseline()    # auto-generate policy from observation

# Observer
guard.endpoint_calls()       # detected service endpoint calls
guard.file_to_endpoint()     # file read -> endpoint correlations
guard.observer_summary()     # services, call counts, bytes
```

## Policy Engine

Define rules for allowed behavior. Three modes: audit, detect, enforce.

```python
from antguard import Guard, Policy

policy = Policy({
    "file": {
        "allow_read": ["./data/*"],
        "deny_read": ["~/.ssh/*", "~/.aws/*"],
    },
    "network": {
        "allow": ["localhost"],
        "deny_all_other": True,
    },
    "process": {
        "deny_shell": True,
    },
    "mode": "detect",
})

with Guard(watch=["./data/"], policy=policy) as g:
    your_code()

for v in g.policy_violations():
    print(f"{v.category}: {v.rule} ({v.severity.value})")
```

Load from YAML: `policy = Policy.from_yaml("antguard-policy.yaml")`

## Combined Report (Bridge)

Optional integration with llmevalkit for unified audit.

```python
from antguard import Guard
from antguard.bridge import UnifiedAudit

with Guard(watch=["./data/"]) as g:
    response = your_code()

# with llmevalkit evaluation (optional)
audit = UnifiedAudit(guard=g, evaluation={"faithfulness": 0.94, ...})
audit.save("./reports/")

# without llmevalkit (standalone)
audit = UnifiedAudit(guard=g)
audit.save("./reports/")
```

## 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 |
| [Policy Engine](demo/demo_07_policy_engine.py) | Define rules, detect violations, baselines |
| [Endpoint Observer](demo/demo_08_endpoint_observer.py) | Detects calls to known service endpoints |
| [Combined Report](demo/demo_09_bridge_report.py) | System behavior + quality in one report |

No models, no API keys, no downloads needed. Every demo runs with plain Python.

**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` (GPU), `pyyaml` (YAML policies), `llmevalkit` (combined report)

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