password-key

Repository on GitHub, which provides public git repositories with URLs.

Repository on GitHub, which uses git. git can track the changes, who made them, and when they were made.

All work is pushed as branches and pull requests between releases, so interim state is publicly reviewable rather than appearing only at release time.

Repository on GitHub, which uses git. git is distributed.

Each release has a unique semantic version, exposed at runtime as password_key.__version__ and via password-key --version.

Semantic Versioning, stated at the top of CHANGELOG.md.

Every release is tagged in git: v1.0.0, v1.1.0 — see https://github.com/nathanramoscfa/password-key/tags.

Non-trivial release notes file in repository: https://github.com/nathanramoscfa/password-key/blob/main/CHANGELOG.md.

No CVE-assigned vulnerability has ever applied to this project, so there is nothing of that kind to identify. The 1.1.0 notes do carry a Security section documenting a security-relevant fix found in internal audit (--print appended an invisible carriage return on Windows, corrupting captured passwords).

Non-trivial SECURITY[.md] file found file in repository: https://github.com/nathanramoscfa/password-key/blob/main/SECURITY.md. [osps_do_02_01]

GitHub Issues.

Met vacuously, and note the form offers no N/A for this criterion. No bug reports have been submitted yet — the repository was first published on 2026-08-10 — so none are unacknowledged. The maintainer monitors the issue tracker and responds.

Met vacuously, for the same reason: no enhancement requests have been received yet, so none are unanswered. The form offers no N/A for this criterion.

https://github.com/nathanramoscfa/password-key/issues — publicly readable and searchable, including closed issues.

SECURITY.md, published in the repository and surfaced by GitHub's Security tab: https://github.com/nathanramoscfa/password-key/blob/main/SECURITY.md

SECURITY.md directs reporters to GitHub's private vulnerability reporting (https://github.com/nathanramoscfa/password-key/security/advisories/new) or to security@arcforgelabs.dev, and asks explicitly that security problems not be filed as public issues.

No vulnerability reports have been received in the last 6 months. SECURITY.md commits to acknowledging reports within a few days.

PEP 517 build via hatchling: python -m build produces a wheel and sdist from a clean checkout. Exercised on every push by the CI build job, which also runs twine check.

Standard PEP 517 tooling: build + hatchling.

CPython, hatchling, build, twine, pytest, ruff, mypy — all FLOSS.

356 pytest tests under tests/, released under the same MIT license as the project. A further 20-test Pester suite covers the standalone PowerShell script in contrib/, including a parity check that its alphabet still matches the Python one.

pytest from the repository root — the standard invocation for Python.

Branch coverage is measured on every test run with a floor enforced in CI. The modules that actually generate secrets are near-complete: generator.py 99%, passphrase.py 95%. Overall is 75%; the remainder is the interactive menu and the platform-specific clipboard backends, which cannot all execute on any single operating system.

GitHub Actions runs on every push and pull request: lint, types, tests across Linux/macOS/Windows × Python 3.9-3.13, a PowerShell suite, a fuzz run, and a packaging build.

CONTRIBUTING.md: “Add tests for any behavior change,” and requires the sampling-bias distribution test to keep passing.

Recent changes demonstrate it: the PowerShell script gained a 20-test Pester suite, and the fuzz harness landed with 245 parametrized pytest cases covering its assertions. Every merged pull request that changed behavior added tests with it.

Documented in CONTRIBUTING.md under “Before you open a PR.”

ruff with pycodestyle, pyflakes, isort, bugbear, pyupgrade, Ruff-specific and bandit security (S) rules; plus mypy --strict. Both run in CI on every push.

CI fails on any ruff or mypy finding, so warnings cannot accumulate. The types job additionally fails if mypy reports it could not honor the configured python_version — mypy otherwise prints a notice and silently retargets, which would let type coverage lapse while the build stayed green.

mypy runs in --strict mode, and for three platforms (linux, darwin, win32) so the Windows-only clipboard path is checked on every commit rather than only when someone runs it on Windows.

Economy of mechanism: ~920 lines, 247 security-relevant, zero runtime dependencies; 'URL-safe by default' is a sweeping simplification that removes an entire class of escaping bugs. Fail-safe defaults: the restricted charset is the default and --full is opt-in and warns; output goes to the clipboard rather than the terminal; --clear wipes only if the clipboard still holds the generated password, so it cannot destroy data the user copied since. Least privilege: workflow tokens are contents:read, id-token:write exists only in the publish job, checkouts use persist-credentials:false; at runtime the tool opens no network connection and writes no files. Least common mechanism: no temp files, no cache, no daemon, no shared state - each run is independent and short-lived. Limited attack surface: zero runtime dependencies is enforced policy (CONTRIBUTING.md). Input validation with allowlists: the charset is an allowlist (RFC 3986 unreserved), length is range-checked, and even --full is an allowlist that excludes quotes, backslash, backtick and space; clipboard helpers are invoked with fixed argv and no shell. Open design: MIT-licensed, with the charset and entropy calculation documented in full - security rests on the OS CSPRNG and entropy, not on obscurity. Psychological acceptability: the project's central thesis is that a password users cannot paste safely is one they will work around, so safe-everywhere output is the default and the unsafe mode explains its consequence. Complete mediation and separation of privilege have limited application in a local CLI with no access-control surface; publishing does require both an OIDC identity and a protected environment. https://github.com/nathanramoscfa/password-key/blob/main/README.md#security-design

Error classes specific to this kind of software, each with the countermeasure applied: (1) Weak or predictable randomness (CWE-338) - all draws come from secrets (the OS CSPRNG); random is never imported, enforced as a documented ground rule. (2) Modulo bias in rejection sampling (CWE-331) - secrets.choice rejects rather than taking a modulus, verified by a chi-squared test over ~64,000 draws in CI; the PowerShell implementation carries the same test, and 256 % 66 != 0 is asserted so the test cannot become vacuous. (3) Injection through unescaped output (CWE-74/78/89) - the default alphabet is the RFC 3986 unreserved set, which carries no special meaning in a URL, a single-quoted SQL literal, or a shell; --full warns that it must be percent-encoded before use in a DSN. (4) Cleartext exposure of secrets (CWE-312/532) - output goes to the clipboard, never to terminal scrollback, and nothing is logged, cached, or written to disk. (5) Insecure shared/temporary state (CWE-377) - none is created. (6) Supply-chain compromise (CWE-1357) - zero runtime dependencies, Actions pinned by commit SHA, CI installs with --require-hashes, and releases publish via OIDC Trusted Publishing with PEP 740 attestations, so no long-lived token exists. (7) Unsafe native interop - a ctypes SetClipboardData call without an explicit restype truncated its 64-bit handle to 32 bits, so a valid handle with zero low bits would have read as failure and freed memory the clipboard already owned; found, fixed, and documented inline. (8) Invisible-character corruption - Windows text-mode stdout turned \n into \r\n, so $(password-key --print) captured a trailing carriage return; script mode now writes \n only, verified by a raw-bytes test. https://github.com/nathanramoscfa/password-key/blob/main/SECURITY.md

The only cryptographic dependency is the operating system CSPRNG, reached through Python's secrets module. No proprietary or unpublished algorithm is involved.

The project implements no cryptographic primitives of its own. Every random draw is secrets.choice, which delegates to the OS CSPRNG and performs its own rejection sampling.

CPython's standard library secrets/os.urandom — FLOSS.

Defaults far exceed NIST minimums: a 32-character URL-safe password is ~193 bits of entropy, and the default 6-word EFF diceware passphrase is ~77.5 bits. Minimum accepted length is 4 characters and the CLI reports the entropy of whatever is generated.

No broken or obsolete algorithms are used. The project performs no hashing, encryption or signing — only random selection from the OS CSPRNG.

No algorithm with known serious weaknesses is used. MD5, SHA-1 and DES appear nowhere in the codebase.

No key agreement protocol exists in this software. It generates random strings locally and performs no network communication of any kind.

The software never stores passwords and never authenticates anyone. It generates a secret, places it on the clipboard, and exits; there is no state, no cache, and nothing written to disk.

All randomness comes from secrets (the OS CSPRNG). random is never imported — this is a documented ground rule in CONTRIBUTING.md, and CI enforces uniformity with a chi-squared test over ~64,000 draws that detects modulo bias. The same test exists for the PowerShell implementation.

Distribution channels use HTTPS exclusively. [osps_br_03_02]

No hash or artifact is retrieved over plain HTTP anywhere in the build or release path. CI dependencies are installed with --require-hashes, and all GitHub Actions are pinned by full commit SHA.

No unpatched vulnerabilities of medium or higher severity affect the delivered package, which has zero runtime dependencies. One medium advisory affects pytest 8.4.2 in the Python 3.9 CI branch; the fix requires Python ≥ 3.10, so no patched release exists for 3.9. It is a test runner on a throwaway CI container and never a dependency of the published package — documented in requirements/README.md.

No critical vulnerabilities have been reported. Five high-severity dependency advisories surfaced in CI tooling were resolved the same day by rescoping the affected lock file.

No credentials are present in the repository. Publishing uses OIDC Trusted Publishing, so there is no API token to leak; workflow checkouts run with persist-credentials: false. Secret scanning and push protection are enabled.

Three independent tools run on every push: GitHub CodeQL with the security-extended query suite, ruff including the bandit-derived security (S) rules, and mypy --strict across three target platforms.

CodeQL's security-extended suite is specifically a common-vulnerability ruleset (CWE-mapped), and ruff's S rules derive from bandit.

CodeQL reports two high-severity py/clear-text-logging-sensitive-data findings. Both are the deliberate secret-output paths — the explicit --show flag, and the fallback when no clipboard is reachable, where withholding the password would destroy a credential the user cannot otherwise retrieve. Both are declared by design in SECURITY.md and dismissed as won't-fix with that reasoning recorded. SECURITY.md also states the condition under which the same rule firing WOULD be a real vulnerability. No other findings are outstanding.

CodeQL runs on every push and pull request, plus a weekly scheduled scan so newly published queries reach existing code. ruff and mypy run on every push.

An Atheris (libFuzzer) harness fuzzes the generator and passphrase APIs for 60 seconds on every push — roughly 58,000 executions per run. It asserts that generate() either honors its contract exactly or raises ValueError, and that entropy is never over-stated.

The project is pure Python, a memory-safe language, and contains no C, C++ or other memory-unsafe code. The only native interaction is ctypes calls into the Win32 clipboard API.

The fuzz harness is assertion-driven, and its assertions are additionally executed as 245 parametrized pytest cases on every CI run, so an assertion that stops working cannot go unnoticed between fuzz runs.

No vulnerabilities have been discovered by dynamic analysis. The fuzz job fails the build on any crash and uploads the reproducing input as an artifact.