GitHub - Pringled/agentcheck: Check what an AI agent can access before you run it

agentcheck is a fast, read-only tool that scans your shell and reports what an AI agent could access: cloud IAM, API keys, Kubernetes, local tools, and more.

Quickstart

# Install
brew install Pringled/tap/agentcheck

What It Scans

Scanner	What it checks
AWS	Active credentials and whether they carry admin-level policies
GCP	Active account and whether it holds owner or editor roles
Azure	Active subscription and Owner / Contributor role assignments
API Keys	100+ env vars and credential files (OpenAI, Stripe, GitHub, etc.)
Kubernetes	Active context, whether it points at a prod cluster
Local	Docker daemon, SSH keys, Terraform config files, .env files

Every finding is tagged LOW, MODERATE, HIGH, or CRITICAL. UNCERTAIN findings (checks that timed out) are shown separately and never trigger CI failure.

Severity policy

Severity	Criteria	Examples
`CRITICAL`	Unrestricted access that cannot be further scoped or constrained.	AWS root credentials; active Vault token; kubectl pointed at a prod cluster; wildcard Kubernetes permissions
`HIGH`	Confirmed access to something dangerous, but scoped to a service, project, or account.	AWS `AdministratorAccess` policy; GCP `roles/owner` on a project; Azure `Owner` role; API keys (OpenAI, Stripe, etc.)
`MODERATE`	Access that could cause harm or enable lateral movement, but requires additional steps or has limited direct impact.	Docker daemon access; SSH keys loaded; Terraform config files in working directory; credential files on disk
`LOW`	Authenticated but no meaningful permissions found.	GCP account active with no project or roles
`UNCERTAIN`	Check timed out or could not complete. Never triggers CI failure.	IAM policy retrieval timeout; API call failed

The default CI threshold (--fail-on high) blocks on HIGH and above, so admin-level IAM access and API keys fail the build in strict mode even though they are not CRITICAL.

Use as a Safety Hook

A useful pattern is to wrap your agent commands so every session starts with a scan:

# Add to your .zshrc or .bashrc
alias claude='agentcheck && claude'
alias cursor='agentcheck && cursor'

CI/CD Integration

Block a pipeline if findings exceed a threshold:

agentcheck --ci                        # fail if any HIGH or CRITICAL finding (default)
agentcheck --ci --fail-on moderate     # fail on MODERATE and above

Exit code 1 when any finding meets or exceeds the threshold, 0 otherwise. UNCERTAIN findings never trigger failure.

# GitHub Actions
- name: agentcheck preflight
  run: agentcheck --ci

Output Formats

agentcheck              # rich table (default)
agentcheck --json       # machine-readable JSON
agentcheck --markdown   # paste into GitHub issues or PRs

JSON output schema

confirmed_total is critical + high + moderate + low. uncertain findings are excluded because they represent incomplete checks, not confirmed risks.

Config File

Create ~/.agentcheck.yaml to set personal defaults, or .agentcheck.yaml in a project directory for project-level settings.

# ~/.agentcheck.yaml

# Default CI failure threshold (overridden by --fail-on on the CLI)
fail_on: critical

# Extra environment variable names to flag as high-risk
extra_env_keys:
  - CORP_INTERNAL_API_KEY
  - MY_SERVICE_TOKEN

# Extra credential files or directories to check
extra_credential_files:
  - path: ~/.config/mycorp/token
    label: "MyCorp internal credentials"

# Extra CLI tool checks (rc==0 means confirmed access)
extra_tool_checks:
  - cmd: ["mycli", "whoami"]
    resource: mycli
    severity: moderate
    description: "Access to mycli confirmed."

CLI flags always take precedence over config values.

Config resolution order and security notes

Resolution order (first found wins):

$AGENTCHECK_CONFIG environment variable
.agentcheck.yaml in the current working directory
~/.agentcheck.yaml in the home directory

Trusted vs. untrusted sources:

$AGENTCHECK_CONFIG and ~/.agentcheck.yaml are trusted sources; you placed them there.

A project-root .agentcheck.yaml is untrusted. A hostile repository must not be able to weaken your security posture when agentcheck is run inside it, so two fields are silently ignored from untrusted sources:

extra_tool_checks: prevents executing attacker-controlled commands
fail_on: prevents raising the CI failure threshold and suppressing findings

Install

# Homebrew (macOS/Linux)
brew tap Pringled/tap
brew install agentcheck

# Go install
go install github.com/Pringled/agentcheck@latest

# Direct download
# https://github.com/Pringled/agentcheck/releases

# Build from source
git clone https://github.com/Pringled/agentcheck.git
cd agentcheck
go build -o agentcheck ./cmd/agentcheck

# Verify
agentcheck version

Author

Thomas van Dongen

License

MIT