Metadata-Version: 2.4
Name: nhi-audit
Version: 0.1.2
Summary: Open-source auditor for Non-Human Identities and AI Agent attack surfaces in cloud environments
Author-email: Abhiram Lanka <lankaabhiram16@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://agent-sentry-beta.vercel.app
Project-URL: Repository, https://github.com/Abhiram-ops/agent-sentry
Project-URL: Bug Tracker, https://github.com/Abhiram-ops/agent-sentry/issues
Project-URL: Documentation, https://agent-sentry-beta.vercel.app/docs
Keywords: security,cloud,iam,ai-agents,non-human-identity,attack-graph
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: networkx>=3.2
Requires-Dist: pyvis>=0.3
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.7
Requires-Dist: jinja2>=3.1
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.6
Requires-Dist: python-dateutil>=2.9
Provides-Extra: aws
Requires-Dist: boto3>=1.34; extra == "aws"
Provides-Extra: azure
Requires-Dist: azure-identity>=1.16; extra == "azure"
Requires-Dist: azure-mgmt-authorization>=4.0; extra == "azure"
Requires-Dist: azure-mgmt-resource>=23.0; extra == "azure"
Provides-Extra: gcp
Requires-Dist: google-auth>=2.28; extra == "gcp"
Requires-Dist: google-api-python-client>=2.120; extra == "gcp"
Provides-Extra: github
Requires-Dist: requests>=2.31; extra == "github"
Provides-Extra: k8s
Requires-Dist: kubernetes>=29.0; extra == "k8s"
Provides-Extra: all-clouds
Requires-Dist: agentsentry[aws]; extra == "all-clouds"
Requires-Dist: agentsentry[azure]; extra == "all-clouds"
Requires-Dist: agentsentry[gcp]; extra == "all-clouds"
Requires-Dist: agentsentry[github]; extra == "all-clouds"
Requires-Dist: agentsentry[k8s]; extra == "all-clouds"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: dashboard
Requires-Dist: streamlit>=1.32; extra == "dashboard"

# AgentSentry 🛡️

![CI](https://github.com/Abhiram-ops/agent-sentry/actions/workflows/ci.yml/badge.svg)
[![PyPI](https://img.shields.io/pypi/v/nhi-audit?label=PyPI&color=00cc6a)](https://pypi.org/project/nhi-audit/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/nhi-audit?color=00cc6a)](https://pypi.org/project/nhi-audit/)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
[![Website](https://img.shields.io/badge/website-agent--sentry--beta.vercel.app-brightgreen)](https://agent-sentry-beta.vercel.app)

**Open-source auditor for Non-Human Identities and AI Agent attack surfaces in cloud environments.**

> *"45 machine identities for every 1 human. Almost none of them are governed."*

AgentSentry discovers every IAM role, API key, service account, and AI agent in your environment, builds an attack graph of their access relationships, and scores the blast radius if any identity is compromised — including a novel **AI-Amplification Factor** that quantifies how autonomous AI agents multiply attack surface.

---

## Why AgentSentry?

Modern enterprises have a critical blind spot: **Non-Human Identities (NHIs)**. While security teams focus on human user access, machine identities — CI/CD service accounts, AI agents, API keys, Lambda execution roles — operate with minimal governance, often with excessive permissions, and almost no rotation discipline.

In 2026, with autonomous AI agents taking real-world actions (sending emails, writing databases, deploying code), a single compromised NHI can cascade into a breach that defeats every perimeter control simultaneously.

No free, open-source tool maps this risk. AgentSentry does.

---

## Features

- 🔍 **NHI Discovery** — Finds all IAM roles, API keys, service accounts, and AI agents
- 📊 **Risk Scoring** — Computes `Risk = Privilege × Reachability × Exposure × AI-Amplification`
- 🕸️ **Attack Graph** — Builds an interactive graph of access relationships and blast radius
- 🤖 **AI Agent Analysis** — Scans LangChain/CrewAI configs for autonomy level and tool risk
- 🗺️ **MITRE ATT&CK Mapping** — Maps every finding to ATT&CK techniques
- 📋 **CISA KEV Enrichment** — Correlates findings against known exploited vulnerabilities
- 🆓 **100% Free** — Runs on AWS free tier, outputs to local HTML, no SaaS required

---

## Quick Start

```bash
# Install from PyPI (no credentials needed to try it)
pip install nhi-audit

# Run against mock environment instantly
agentsentry scan mock

# Check what providers are ready on your machine
agentsentry providers

# Scan your local machine (no credentials needed)
agentsentry scan local

# Scan AWS (requires aws configure)
pip install nhi-audit[aws]
agentsentry scan aws

# Scan everything that's configured
agentsentry scan all

# Generate interactive attack graph
agentsentry scan mock --visualize

# Analyze blast radius for a specific identity
agentsentry blast "ml-pipeline-executor"
```

### Provider-specific installs

```bash
pip install nhi-audit[aws]        # + AWS IAM, Lambda, S3, Secrets Manager
pip install nhi-audit[azure]      # + Managed Identities, Service Principals
pip install nhi-audit[gcp]        # + Service Accounts, SA Keys
pip install nhi-audit[github]     # + PATs, Deploy Keys, Actions Secrets
pip install nhi-audit[k8s]        # + ServiceAccounts, ClusterRoleBindings
pip install nhi-audit[all-clouds] # Everything
```

---

## Sample Output

```
╭────────────────────────────────╮
│  AgentSentry  v0.1.0           │
│  NHI & AI Agent Risk Auditor   │
╰────────────────────────────────╯

 NHIs Discovered: 6   Critical: 3   High: 1   AI Agents: 2

┌──────────────────────────────┬──────────────┬────────────┬───────┬──────────┐
│ Identity                     │ Type         │ Risk       │ Score │ Findings │
├──────────────────────────────┼──────────────┼────────────┼───────┼──────────┤
│ langchain-crm-agent          │ ai_agent     │ ● CRITICAL │ 150.0 │    2     │
│ ml-pipeline-executor         │ iam_role     │ ● CRITICAL │ 112.5 │    3     │
│ github-actions-prod-deploy   │ github_secret│ ● CRITICAL │  90.0 │    2     │
│ legacy-reporting-service-key │ iam_user_key │ ● HIGH     │  52.5 │    2     │
└──────────────────────────────┴──────────────┴────────────┴───────┴──────────┘

⚠  langchain-crm-agent — Fully Autonomous AI Agent With Irreversible Tools
   This agent has FULLY_AUTONOMOUS execution with delete_record, send_email.
   AI-Amplification Factor: 10.0x
   Remediation: Implement human-in-the-loop approval for all irreversible tools.
   MITRE: T1651, T1059
```

---

## The Scoring Model

```
NHI Risk Score = P × R × E × A

P = Privilege Score      (1–10)  How powerful are the permissions?
R = Reachability Score   (1–3)   How accessible is this identity to attackers?
E = Exposure Score       (1–5)   How poor is the credential lifecycle?
A = AI-Amplification     (1–60)  [NOVEL] How much does agent autonomy multiply blast radius?

Score ≥ 100 → CRITICAL
Score ≥ 50  → HIGH
Score ≥ 20  → MEDIUM
Score < 20  → LOW
```

The **AI-Amplification Factor (A)** is the novel academic contribution of this project.
No existing NHI risk framework accounts for how autonomous AI agents compound the impact
of a compromised machine identity. See the [paper](paper/) for the formal model.

---

## Architecture

```
agentsentry/
├── core/
│   ├── models.py    # Data models (NonHumanIdentity, Resource, Finding)
│   ├── scorer.py    # Risk scoring engine — P × R × E × A
│   └── graph.py     # NHI Attack Graph (NetworkX + Pyvis)
├── scanners/
│   ├── mock.py      # Demo environment — no credentials needed
│   ├── aws.py       # AWS IAM scanner (Phase 1)
│   └── langchain.py # AI agent static analyzer (Phase 3)
├── enrichment/
│   ├── cisa_kev.py  # CISA KEV feed correlation
│   └── mitre.py     # MITRE ATT&CK mapping
└── cli.py           # Click-based CLI
```

---

## Roadmap

- [x] Core scoring model (P × R × E × A)
- [x] Mock scanner for demos
- [x] CLI with Rich terminal output
- [x] Interactive attack graph visualization
- [ ] AWS IAM scanner (boto3)
- [ ] LangChain agent static analyzer
- [ ] CISA KEV enrichment
- [ ] MITRE ATT&CK enrichment
- [ ] Azure AD service principal scanner
- [ ] GitHub Actions secrets scanner
- [ ] Streamlit dashboard
- [ ] Research paper (arXiv)

---

## Contributing

This is an open research project. Contributions welcome — especially:
- Cloud provider scanner implementations
- Additional AI agent framework support (CrewAI, AutoGen, Semantic Kernel)
- Threat intelligence enrichment integrations
- Validation datasets for the scoring model

---

## Paper

The formal scoring model and evaluation methodology is being written up as a research paper.
Pre-print will be available on arXiv. See [`paper/`](paper/) for the LaTeX source.

---

## License

MIT — use it, fork it, build on it.

---

*Built by Abhiram Lanka | Addressing the NHI blindspot in enterprise security*
