Cloudkeys

pip install cognis-cloudkeys
cloudkeys scan .            # → prioritized findings in seconds

🔎 Example output

Real, reproducible output from the tool — runs offline:

$ cloudkeys-emit --version
cloudkeys 0.1.0

$ cloudkeys-emit --help
usage: cloudkeys [-h] [--version] [--format {table,json,sarif}]
                 {scan,feeds} ...

Find leaked AWS/GCP/Azure credentials and classify blast radius (defensive).

positional arguments:
  {scan,feeds}
    scan                scan files/dirs (or - for stdin) for leaked keys
    feeds               cloud IP-range data feeds (real, keyless, offline-
                        capable)

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --format {table,json,sarif}
                        output format (table | json | sarif 2.1.0)

Blocks above are real cloudkeys output — reproduce them from a clone.

Sample result format (illustrative values — run on your own data for real findings):

{
  "cloudkeys": {
    "platform": "stix",
    "data": [
      {
        "id": "1234567890abcdef",
        "type": "indicator",
        "name": "Example Indicator",
        "description": "This is an example indicator.",
        "created_by_ref": "user1",
        "modified_by_ref": "user2"
      }
    ]
  }
}

Usage — step by step

1. Install:

   pip install -e .
   

2. Scan a path (files and/or directories, recursively) for leaked AWS/GCP/Azure credentials with the scan subcommand. The paths argument is variadic and accepts - for stdin:

   cloudkeys scan ./src
   

   Scan multiple targets, or pipe content in:

   cloudkeys scan ./src ./config
   git show HEAD | cloudkeys scan -
   

3. Get machine-readable output with the global --format flag (placed before the subcommand). json for any tooling, sarif for code-scanning dashboards:

   cloudkeys --format json  scan ./src
   cloudkeys --format sarif scan ./src > cloudkeys.sarif   # SARIF 2.1.0
   

4. Read the result. Each finding lists SEVERITY, DETECTOR, provider, file:line, the matched secret, its entropy, a blast: (blast-radius) assessment, and a fix: remediation, plus a severity-count summary. The process exits 1 when any credential is found, 0 when clean, 2 on runtime error with nothing scanned.

5. Use it in CI — block a commit/build that leaks a cloud key:

   cloudkeys --format json scan . || { echo "Leaked cloud credential detected"; exit 1; }
   

Contents

• Why cloudkeys? · Features · Quick start · Example · Demos · SARIF export · Architecture · AI stack · How it compares · Integrations · Install anywhere · Related · Contributing

Why cloudkeys?

key triage

cloudkeys is single-purpose, scriptable, and self-hostable: point it at a target, get prioritized results in the format your workflow already speaks (table · JSON · SARIF), gate CI on it, and let agents drive it over MCP.

Features

• ✅ Shannon Entropy
• ✅ Redact
• ✅ Blast Radius
• ✅ Scan Text
• ✅ Scan Path
• ✅ Runs on Linux/macOS/Windows · Docker · devcontainer
• ✅ Ports in Python, JavaScript, Go, and Rust (ports/)

Quick start

pip install cognis-cloudkeys
cloudkeys --version
cloudkeys scan .                       # scan current project
cloudkeys scan . --format json         # machine-readable
cloudkeys scan . --fail-on high        # CI gate (non-zero exit)

Example

$ cloudkeys scan .
  [HIGH    ] CLO-001  example finding             (./src/app.py)
  [MEDIUM  ] CLO-002  another signal              (./config.yaml)

  2 findings · risk score 5 · 38ms

Demos — real-world leak scenarios

Runnable, self-contained scenarios under demos/. Each folder has a realistic input file (in the format the leak actually shows up in) and a SCENARIO.md explaining where the data came from, the exact command, what to expect, and how to act. Every credential is a fake placeholder shaped like the real format — cloudkeys never uses a discovered secret.

Demo	Scenario	Detectors exercised
01-basic	Accidentally committed app config (.env)	aws akid/secret, gcp api key, azure storage/client-secret
02-clean	Clean file — no findings	—
03-mixed	Mixed signal text	—
04-aws-credentials-file	A committed ~/.aws/credentials with two profiles	aws_access_key_id, aws_secret_access_key
05-gcp-api-key	Unrestricted GCP/Firebase API key in a frontend bundle	gcp_api_key
06-terraform-tfvars	Secrets baked into terraform.tfvars	azure_client_secret, aws_access_key_id
07-ci-pipeline-env	Secrets pasted into a CI workflow env:	aws_access_key_id (STS), aws_session_token, gcp_api_key
08-kubernetes-secret	A kind: Secret manifest in a GitOps repo	private_key_pem, azure_sas_token
09-git-diff-precommit	Block a leak in a pre-commit hook (stdin)	aws_access_key_id, aws_secret_access_key
10-dotenv-clean-baseline	A correct .env.example (the green-CI baseline)	— (exit 0)

cloudkeys scan demos/04-aws-credentials-file/credentials          # 4 findings
git diff --cached | cloudkeys scan -                              # pre-commit gate (demo 09)
cloudkeys scan demos/10-dotenv-clean-baseline/.env.example        # clean, exit 0

SARIF 2.1.0 export

Emit OASIS SARIF v2.1.0 so findings flow into GitHub code-scanning, Azure DevOps, or any SARIF viewer. Severities map to SARIF level (error/warning/note) and a numeric security-severity for ranking, one rule per detector.

cloudkeys --format sarif scan . > cloudkeys.sarif

In GitHub Actions:

- run: cloudkeys --format sarif scan . > cloudkeys.sarif || true
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: cloudkeys.sarif

Cloud IP attribution — real data feeds (edge / air-gap)

A leaked key is more actionable when you can also say which cloud the endpoints in the same file belong to. cloudkeys ships an edge/air-gap-deployable ingestion layer (cloudkeys/datafeeds.py) that pulls two real, authoritative, keyless public feeds, caches them to disk, and re-serves them offline:

feed id	source	what it gives
aws-ip-ranges	https://ip-ranges.amazonaws.com/ip-ranges.json	AWS CIDR → service + region
gcp-ip-ranges	https://www.gstatic.com/ipranges/cloud.json	GCP CIDR → service + scope/region

The feeds command

cloudkeys feeds list                       # the two feeds + cache freshness
cloudkeys feeds update                     # fetch + cache (online)
cloudkeys feeds get aws-ip-ranges --offline
cloudkeys feeds attribute 3.4.12.4         # -> AWS AMAZON eu-west-1 (3.4.12.4/32)
cloudkeys feeds attribute 34.1.208.1 --offline

Enrich a scan

--attribute extracts IPs found while scanning and attributes each to AWS/GCP; --offline serves from cache only (never touches the network):

cloudkeys --format json scan --attribute --offline demos/11-ip-attribution/

The JSON gains an ip_attributions map (ip → {cloud,service,region,cidr}); the table output gets a Cloud IP attribution block.

Edge / air-gap workflow

The cache lives at COGNIS_FEEDS_CACHE (default ~/.cache/cognis-feeds). To run on a disconnected enclave, refresh on a connected host, snapshot the cache, sneakernet it across, and import:

# connected host
cloudkeys feeds update
python -m cloudkeys.datafeeds snapshot-export feeds.tar.gz

# air-gapped host
export COGNIS_FEEDS_CACHE=/opt/cognis-feeds
python -m cloudkeys.datafeeds snapshot-import feeds.tar.gz
cloudkeys feeds attribute 3.4.12.4 --offline      # works with zero network

Tests run fully offline against a trimmed fixture cache committed under tests/fixtures/cognis-feeds/, so CI is green air-gapped.

Architecture

flowchart LR
  IN[target / manifest] --> P[cloudkeys<br/>checks + rules]
  P --> OUT[findings (JSON / SARIF)]

Use it from any AI stack

cloudkeys is interoperable with every popular way of using AI:

• MCP server — cloudkeys mcp (Claude Desktop, Cursor, Cognis.Studio, uncensored-fleet)
• OpenAI-compatible / JSON — pipe cloudkeys scan . --format json into any agent or LLM
• LangChain · CrewAI · AutoGen · LlamaIndex — wrap the CLI/JSON as a tool in one line
• CI / scripts — exit codes + SARIF for non-AI pipelines

How it compares

	Cognis cloudkeys	trufflehog
Self-hostable, no account	✅	varies
Single command, zero config	✅	⚠️
JSON + SARIF for CI	✅	varies
MCP-native (AI agents)	✅	❌
Polyglot ports (JS/Go/Rust)	✅	❌
Open license	✅ COCL	varies

Built in the spirit of trufflehog, re-framed the Cognis way. Missing a credit? Open a PR.

Integrations

Pipes into your stack: SARIF for code-scanning, JSON for anything, an MCP server (cloudkeys mcp) for AI agents, and a webhook forwarder for SIEM/Slack/Jira. See docs/INTEGRATIONS.md.

Install — every way, every platform

pip install "git+https://github.com/cognis-digital/cloudkeys.git"    # pip (works today)
pipx install "git+https://github.com/cognis-digital/cloudkeys.git"   # isolated CLI
uv tool install "git+https://github.com/cognis-digital/cloudkeys.git" # uv
pip install cognis-cloudkeys                                          # PyPI (when published)
docker run --rm ghcr.io/cognis-digital/cloudkeys:latest --help        # Docker
brew install cognis-digital/tap/cloudkeys                             # Homebrew tap
curl -fsSL https://raw.githubusercontent.com/cognis-digital/cloudkeys/main/install.sh | sh

Linux	macOS	Windows	Docker	Cloud
scripts/setup-linux.sh	scripts/setup-macos.sh	scripts/setup-windows.ps1	docker run ghcr.io/cognis-digital/cloudkeys	DEPLOY.md (AWS/Azure/GCP/k8s)

Related Cognis tools

• portfan — Summarize and diff nmap XML into prioritized, attackable findings
• subhunt — Aggregate & dedupe subdomain enumeration from multiple sources
• dirsight — Analyze web content-discovery output (ffuf/gobuster) into ranked endpoints
• jwtinspect — Decode JWTs and lint for alg=none, weak secrets, and missing claims
• corsaudit — Detect permissive/misconfigured CORS from headers or a config
• headerscan — Grade HTTP security headers (CSP/HSTS/XFO) A-F from a response dump

Explore the suite → 🗂️ all 170+ tools · ⭐ awesome-cognis · 🔗 cognis-sources · 🤖 uncensored-fleet · 🧠 engram

Contributing

PRs, new rules, and demo scenarios are welcome under the collaboration-pull model — see CONTRIBUTING.md and SECURITY.md.

⭐ If cloudkeys saved you time, star it — it genuinely helps others find it.

Interoperability

{} composes with the 300+ tool Cognis suite — JSON in/out and a shared OpenAI-compatible /v1 backbone. See INTEROP.md for the suite map, composition patterns, and reference stacks.

License

Source-available under the Cognis Open Collaboration License (COCL) v1.0 — free for personal, internal-evaluation, research, and educational use; commercial / production use requires a license ([email protected]). See LICENSE.

---