AgentSentry Docs
Open-source NHI & AI agent risk scanner. Discovers every machine identity across AWS, Azure, GCP, GitHub, Kubernetes, and your local machine — scores blast radius with P×R×E×A.
Quick Start
agentsentry scan mock runs a full multi-cloud demo instantly.pip install nhi-audit # Fix PATH on Windows (run once) python -m agentsentry --install-path # Recommended for first-time users agentsentry interactive # Or go straight to scanning agentsentry scan mock # full demo, no credentials agentsentry scan local # scan this machine now
Installation
Core package
pip install nhi-audit
Includes the local scanner, mock demo, and AI agent code scanner. No cloud credentials needed.
With cloud providers
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 at once
Provider Setup
🖥️ Local (no setup)
agentsentry scan local agentsentry scan local --path ./my-project # specific directory
Scans env vars, SSH keys, .env files, cloud credential files, and source code for hardcoded secrets. No credentials required.
☁️ AWS
aws configure # enter Access Key + Secret agentsentry scan aws agentsentry scan aws --region eu-west-1 # specific region agentsentry scan aws --profile myprofile # named profile
Minimum IAM permissions: iam:List*, iam:Get*, sts:GetCallerIdentity, lambda:ListFunctions, s3:ListAllMyBuckets
🔷 Azure
az login # browser opens, sign in agentsentry scan azure
Or with a service principal:
set AZURE_TENANT_ID=<tenant> set AZURE_CLIENT_ID=<client> set AZURE_CLIENT_SECRET=<secret> agentsentry scan azure
🟡 GCP
gcloud auth application-default login # browser opens agentsentry scan gcp
Or with a service account key file:
set GOOGLE_APPLICATION_CREDENTIALS=C:path okey.json agentsentry scan gcp
🐙 GitHub
# Create token at: github.com/settings/tokens # Scopes: repo, read:org, read:user set GITHUB_TOKEN=ghp_your_token_here agentsentry scan github agentsentry scan github --org myorganisation
☸️ Kubernetes
kubectl config use-context my-cluster agentsentry scan k8s agentsentry scan k8s --namespace production agentsentry scan k8s --context prod-cluster
🤖 AI Agent Code
agentsentry scan agents --path ./my-project # Scans LangChain / CrewAI / AutoGen Python files
All Commands
# Scanning agentsentry scan mock agentsentry scan local --path ./myproject agentsentry scan aws agentsentry scan azure agentsentry scan gcp agentsentry scan github --org myorg agentsentry scan k8s --namespace production --context prod agentsentry scan agents --path . agentsentry scan all # auto-detect + scan all ready # Flags (work on any scan command) agentsentry scan aws --visualize # interactive HTML attack graph agentsentry scan aws --enrich # + CISA KEV threat intel agentsentry scan aws --json # JSON output # Provider info agentsentry providers # list all + readiness agentsentry permissions aws # exact permissions needed # Analysis agentsentry blast "ml-pipeline" # blast radius for one NHI # Guided mode agentsentry interactive # numbered provider picker # Utilities agentsentry --version python -m agentsentry --install-path # fix Windows PATH
Risk Scoring: P×R×E×A
Risk = P × R × E × A P Privilege Score 1–10 What can this identity DO? R Reachability Score 1–3 How accessible is it to attackers? E Exposure Score 1–5 How poor is the credential lifecycle? A AI-Amplification 1–60 Does autonomous AI multiply blast radius? CRITICAL ≥ 100 | HIGH ≥ 50 | MEDIUM ≥ 20 | LOW < 20
| Factor | Example (low) | Example (high) |
|---|---|---|
P — Privilege | ReadOnly role (1.0) | AdministratorAccess (10.0) |
R — Reachability | Internal only (1.0) | Internet-facing (3.0) |
E — Exposure | Rotated 7 days ago (1.0) | Never rotated (5.0) |
A — AI-Amplification | Read-only bot (1.0) | Autonomous agent with delete tools (60.0) |
Interactive Mode
Run agentsentry interactive for a guided experience — no flags needed.
agentsentry interactive # Shows a numbered menu: # 1 ● local ready This machine — env vars, SSH keys, files # 2 ● aws ready Amazon Web Services # 3 ● azure no sdk pip install nhi-audit[azure] # 4 ● github no creds set GITHUB_TOKEN=... # ... # Enter numbers to scan (e.g. 1,2 or all): 1,2 # Directory to scan [.]: ./my-project
If a provider SDK is missing, it offers to install it inline. If credentials are missing, it shows exactly what command to run.
Standalone Executable
No Python installation required. Download a pre-built binary from GitHub Releases.
| Platform | File |
|---|---|
| Windows | agentsentry-windows.exe |
| macOS | agentsentry-macos |
| Linux | agentsentry-linux |
# Windows — run directly agentsentry-windows.exe interactive # macOS / Linux chmod +x agentsentry-macos ./agentsentry-macos interactive
Common Findings & Fixes
Apply least-privilege. Use CloudTrail access advisor to see what the role actually uses, then replace AdministratorAccess with a specific policy.
agentsentry scan aws
Rotate immediately: create a new key, update all consumers, deactivate the old key, delete after 7 days.
aws iam create-access-key
Add a human-in-the-loop approval callback for all irreversible tools (send_email, delete_record). Set max_iterations cap.
agentsentry scan agents --path .
Scope to a specific namespace with a Role instead of ClusterRole. Never give cluster-admin to a ServiceAccount.
agentsentry scan k8s
Add passphrase: ssh-keygen -p -f ~/.ssh/id_rsa
agentsentry scan local
Add .env to .gitignore. Move secrets to a secrets manager. Rotate any that were ever committed.
agentsentry scan local --path .