Auditable random credential generator for AI agents and machine-readable pipelines. Replaces ad-hoc password generation with a verifiable contract backed by the OS CSPRNG.
# zero-install (no clone, no compile)
npx -y @secretgenerator/cli password --json --show-crack-time
# permanent install
brew install rafaelperoco/tap/secretgenerator
# Model Context Protocol server (Claude / Cursor / Cline)
npx -y @secretgenerator/mcpOutput is stable JSON (schema v1):
{
"schema_version": 1,
"password": "VoJgEDVnCoTVMx8cLnMwmHnz",
"entropy_bits": 142.9,
"charset_id": "alphanum-v1",
"algorithm": "crypto/rand+rejection-sampling",
"subcommand": "password",
"version": "2.0.0",
"request_id": "f4c54f9c-0f57-4d58-83be-7937cbe077f7",
"timestamp_utc": "2026-04-29T22:35:11.077695Z",
"crack_time_estimates": [
{
"profile_id": "nation-state-v1",
"human_readable": "1.2e+10 times the age of the universe"
}
]
}Pin the schema with --require-schema-version=1.
Why not let an LLM generate the password directly? Recent research (Irregular Security, 2025) shows Claude, GPT, and Gemini produce passwords with ~20 bits of effective entropy instead of the ~100 bits the same models claim. Specific 16-character sequences recurred 18 times out of 50 attempts. LLMs cannot sample uniformly. secretgenerator is the correct primitive: an LLM tool-calls it instead of inventing the credential itself.
| Subcommand | Use case |
|---|---|
password |
Random password from a named charset (default 20 chars, ~119 bits). |
passphrase |
Diceware passphrase from the EFF Large Wordlist (default 8 words, ~103 bits). |
secret |
Raw bytes from the OS CSPRNG, encoded as URL-safe base64 (default 32 bytes / 256 bits). |
api-key |
Token in prefix_random form (Stripe-style). |
pin |
Numeric PIN with weak-PIN blocklist enforced. |
entropy |
Estimate the entropy and crack time of an existing password. |
secretgenerator password --json --show-crack-time
secretgenerator passphrase --words 10 --separator -
secretgenerator secret --bytes 32
secretgenerator api-key --prefix sk_live --length 40
secretgenerator pin --digits 6 --acknowledge-low-entropy
echo -n 'Tr0ub4dor&3' | secretgenerator entropy --show-crack-timeFull flag reference: docs/SUBCOMMANDS.md.
| Method | Command |
|---|---|
| npm (zero-install) | npx -y @secretgenerator/cli |
| Homebrew | brew install rafaelperoco/tap/secretgenerator |
| MCP server | npx -y @secretgenerator/mcp |
| Container | docker run --rm ghcr.io/rafaelperoco/secretgenerator:v2.0.0 |
| Go install | go install github.com/rafaelperoco/secretgenerator/cmd/secretgenerator@v2.0.0 |
| GitHub Actions | uses: rafaelperoco/secretgenerator/.github/actions/setup-secretgenerator@v2.0.0 |
| Python (PyPI) | pip install secretgenerator-py (CLI binary installed separately) |
| Rust (crates.io) | cargo add secretgenerator (CLI binary installed separately) |
| Verified manual | See verified install below. |
Every release is signed end-to-end. Verify before extracting:
# 1. Download the artifacts.
curl -LO https://github.com/rafaelperoco/secretgenerator/releases/download/v2.0.0/secretgenerator_2.0.0_linux_amd64.tar.gz
curl -LO https://github.com/rafaelperoco/secretgenerator/releases/download/v2.0.0/checksums.txt
curl -LO https://github.com/rafaelperoco/secretgenerator/releases/download/v2.0.0/checksums.txt.sig
curl -LO https://github.com/rafaelperoco/secretgenerator/releases/download/v2.0.0/checksums.txt.pem
# 2. Verify the cosign signature (Sigstore/Fulcio + GitHub OIDC).
cosign verify-blob \
--certificate checksums.txt.pem \
--signature checksums.txt.sig \
--certificate-identity-regexp "https://github.com/rafaelperoco/secretgenerator/.github/workflows/release.yml@refs/tags/v.*" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
checksums.txt
# 3. Verify the binary checksum.
sha256sum -c checksums.txt --ignore-missing
# 4. Extract and install.
tar -xzf secretgenerator_2.0.0_linux_amd64.tar.gz
sudo mv secretgenerator /usr/local/bin/The container image is also signed:
cosign verify ghcr.io/rafaelperoco/secretgenerator:v2.0.0 \
--certificate-identity-regexp "https://github.com/rafaelperoco/secretgenerator/.github/workflows/release.yml@refs/tags/v.*" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"Full procedure including SLSA provenance verification: docs/AUDIT.md.
- Stable JSON contract (schema v1) with
--json. Versioned, schema-pinnable, JSON-Schema-validated. - Hard entropy floors aligned with NIST SP 800-63B-4 and NIST SP 800-131A Rev. 3.
- Class-requirement guarantees via rejection sampling.
- Auditable provenance: SLSA Level 3, cosign keyless signatures, CycloneDX SBOMs.
- Audit log with SHA-256 password fingerprints (never plaintext).
- Time-to-break estimates under five named attacker profiles.
import "github.com/rafaelperoco/secretgenerator/pkg/secretgen"
res, err := secretgen.Password(secretgen.PasswordOptions{
Length: 24,
CharsetID: "alphanum-symbols-v1",
RequiredClasses: "lower,upper,digit,symbol",
})
if err != nil { /* errors.Is(err, secretgen.ErrBelowEntropyFloor) etc. */ }
fmt.Println(res.Password, "entropy:", res.EntropyBits)
for _, e := range secretgen.EstimateCrackTime(res.EntropyBits) {
fmt.Println(e.ProfileID, e.HumanReadable)
}API stability is documented in pkg/secretgen/doc.go.
Ready-to-run snippets for Python, Node.js, Ruby, Rust, Bash, and Go live
under examples/. All of them produce the same
schema-v1 output and pin --require-schema-version=1.
- docs/SUBCOMMANDS.md — Every flag of every subcommand.
- docs/SCHEMA.md — Output schema reference.
- docs/CRYPTO.md — Entropy source per OS, NIST/OWASP mapping.
- docs/AUDIT.md — End-to-end release verification.
- SECURITY.md — Threat model, vulnerability reporting.
- CHANGELOG.md — Release history.
- CONTRIBUTING.md — Development setup, required CI gates.
MIT. The embedded EFF Large Wordlist is CC-BY-3.0; see
internal/words/eff_large_wordlist.txt and the EFF announcement at
https://www.eff.org/dice.
Rafael Peroco