Documentation

AgentSentry CLI

Open-source NHI scanner, runs locally, zero data upload, one command to audit your entire cloud.

What's New Installation Quick start Providers Output formats Advanced API Key

What's New

v0.2.0Latest

Data-driven least-privilege, scan aws --analyze-usage pulls IAM Access Advisor data and names the exact granted-but-unused services that are safe to revoke (finding NHI-006)
Continuous monitoring, scan --save records to a local history store; agentsentry diff aws shows what changed since the last scan (new identities, newly-zombie, rotation-due)
Deeper AWS coverage, Secrets Manager, RDS, and DynamoDB now scanned as crown-jewel resources, so the attack graph reaches your most sensitive targets
Real policy documents, managed policies are now fetched and analyzed by their actual permissions, not just their names (a custom policy with "Action": "*" no longer hides as INFO)

v0.1.10

Fix ~/.aws/config being over-scored, it stores profile names, not keys, so it now correctly scores as INFO
Fix GCP credentials.db showing wrong "Hardcoded secrets" description
Exclude tests/ directories from source scanner to eliminate intentional test-fixture false positives
Tighten secret regex: now requires 16+ characters with at least one uppercase letter or digit to cut noise from short placeholder values

v0.1.9

Fix agentsentry scan local --pro crash on LOW-risk identities (Rich markup typo)
Block Xbox Live / WindowsLive / MicrosoftAccount consumer tokens from Windows Credential Manager scan (was 22 false positives)
Cloud credential files now get realistic privilege scores: AWS credentials → HIGH, kubeconfig → CRITICAL
Escape all credential names in Rich output to prevent markup injection

v0.1.8

Windows Credential Manager scan (cmdkey /list), no admin required
macOS Keychain scan (security dump-keychain), metadata only, never reads secret values
Cross-platform Docker detection via subprocess (fixes Windows named-pipe blind spot)
Expanded credential file coverage: Azure CLI, GitHub CLI, Terraform Cloud, Windows gcloud path

Installation

AgentSentry requires Python 3.10+. The PyPI package is nhi-audit; the CLI command is agentsentry.

bash

# Base install (local scan, no cloud credentials needed)
$ pip install nhi-audit
 
# With all provider extras
$ pip install 'nhi-audit[aws,azure,gcp,github,k8s]'
 
# Verify
$ agentsentry --version

Quick start

The fastest way to see AgentSentry in action, scan your local environment. No credentials needed.

bash

# Scan local environment (no credentials needed)
$ agentsentry scan local
 
# Full analyst report with attack narratives per identity
$ agentsentry scan local --pro
 
# Scan everything configured on this machine
$ agentsentry scan all
 
# Open the interactive attack graph in your browser
$ agentsentry visualize

Provider setup & scan commands

Local Machine (free, no credentials)

Scans environment variables, .env files, SSH keys, cloud credential files, source code, and OS credential stores. On Windows it reads Windows Credential Manager (cmdkey /list), consumer tokens (Xbox Live, MicrosoftAccount) are automatically filtered. On macOS it reads Keychain metadata (security dump-keychain), secret values are never read.

bash

# Quick scan
$ agentsentry scan local
 
# Full analyst report (--pro): attack narratives + MITRE mappings + remediation steps
$ agentsentry scan local --pro

Amazon Web Services (AWS)

bash

# Install AWS extra
$ pip install 'nhi-audit[aws]'
 
# Configure credentials
$ export AWS_PROFILE=my-profile
 
# Scan
$ agentsentry scan aws

Microsoft Azure

bash

$ pip install 'nhi-audit[azure]'
$ az login
$ agentsentry scan azure

Google Cloud (GCP)

bash

$ pip install 'nhi-audit[gcp]'
$ gcloud auth application-default login
$ agentsentry scan gcp

GitHub

bash

$ pip install nhi-audit
$ export GITHUB_TOKEN=<your-pat>
$ agentsentry scan github

Kubernetes

bash

$ pip install 'nhi-audit[k8s]'
$ kubectl config use-context <your-cluster>
$ agentsentry scan k8s

Output formats

Export findings in multiple formats for integration with your existing security toolchain.

bash

# Default: rich terminal table
$ agentsentry scan all
 
# --pro: full analyst report per identity (attack narrative + MITRE + remediation)
$ agentsentry scan local --pro
 
# JSON (for SIEM / automation)
$ agentsentry scan all --output json > findings.json
 
# CSV (for spreadsheets)
$ agentsentry scan all --output csv > findings.csv
 
# Open attack graph in browser
$ agentsentry visualize
 
# Save graph as HTML file
$ agentsentry visualize --save report.html

--pro analyst report

Pass --pro to get a full analyst-grade breakdown for each identity: a plain-English "WHAT IS THIS?" explanation, step-by-step attacker exploit narrative with real commands, MITRE ATT&CK technique mappings, and numbered remediation steps. Works with agentsentry scan local today.

Advanced usage

Filter by risk threshold, target a specific AWS profile, or run in CI/CD pipelines.

bash

# Show only CRITICAL and HIGH findings
$ agentsentry scan all --min-risk HIGH
 
# Use a specific AWS profile
$ export AWS_PROFILE=prod
$ agentsentry scan aws
 
# Non-zero exit code on CRITICAL findings (great for CI)
$ agentsentry scan all --fail-on CRITICAL
 
# Scan a specific LangChain / CrewAI project directory
$ agentsentry scan agents ./my-agent-project

GitHub Actions example:

yaml

- name: AgentSentry NHI Scan
  run: |
    pip install nhi-audit[aws]
    agentsentry scan aws --output json --fail-on CRITICAL
  env:
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

Testing v0.2.0

New features in 0.2.0: explicit consent gates, continuous scan history, data-driven least-privilege via AWS Access Advisor, and deeper resource coverage (Secrets Manager, RDS, DynamoDB). Here's what to test.

Step 1, Version & Consent (30 seconds, no setup)

Verify the version and test the new consent gate:

bash

# Verify version
$ agentsentry --version
 
# Activate (use your activation code)
$ agentsentry activate YOUR-CODE
 
# → Expect: consent panel asking 'Do you accept Terms & Privacy?', type 'y'

This is the new consent gate. Answering n should cancel with exit 1.

Step 2, Continuous Monitoring (1 minute, no AWS needed)

Test the new scan history + diff feature (uses mock data):

bash

# Save a mock scan to history
$ agentsentry scan mock --save
 
# List past scans
$ agentsentry history
 
# Compare current scan to baseline (should show 'no changes')
$ agentsentry diff mock

--save writes to a local SQLite store; diff scans again and shows what changed.

Step 3, Least-Privilege Analysis (AWS, the headline feature)

Before running this, ensure your AWS read-only role has these 4 new permissions:

bash

iam:GenerateServiceLastAccessedDetails
iam:GetServiceLastAccessedDetails
rds:DescribeDBInstances
dynamodb:ListTables

Then run the new --analyze-usage flag:

bash

# Data-driven least-privilege: find unused permissions
$ agentsentry scan aws --analyze-usage
 
# → Expect: NHI-006 'Excessive Unused Permissions' findings
#   Each shows exact services granted but never used.

This queries AWS Access Advisor per identity, runs slower but gives precise, defensible revocation recommendations.

Your AgentSentry API Key

Your AgentSentry API key authenticates the CLI with our backend, it tells us who you are, what tier you're on, and tracks credit usage when you run scans.

What it is used for

Authenticating the agentsentry activate command
Gating Pro features and deducting scan credits
Identifying your account when you contact support

What it is NOT used for

Connecting to AWS, Azure, or GCP, your cloud credentials stay on your machine and never touch our servers
Linking to any third-party platform or deployment tool

How to retrieve your full API key

For security, your full API key is never displayed in the dashboard, only a short preview is shown. If you need the full key, email support@agentsentry.org from your registered address and we'll send it securely.