dbmask

https://github.com/sealandseacat/dbmask

The repository is git, so every change records its author, timestamp and diff. https://github.com/sealandseacat/dbmask/commits/main

Work lands on main continuously through pull requests between releases; main is not a release-only branch. The v0.1.1 work was developed as a series of individually reviewable commits on the v0.1.1-hardening branch and merged as pull request #13.

git.

Each release carries a unique version identifier declared in pyproject.toml and published under that version on PyPI and as a git tag: 0.1.0 and 0.1.1.

Every release is tagged in git: v0.1.0, v0.1.1. https://github.com/sealandseacat/dbmask/tags

https://github.com/sealandseacat/dbmask/blob/main/CHANGELOG.md — hand-written release notes in Keep a Changelog format, grouped into Security / Fixed / Added / Changed, with links to the individual issues and to the security advisory. The same notes form the body of each GitHub release.

The v0.1.1 release notes open with a Security section that names the one vulnerability fixed in that release and links its advisory, GHSA-2jwm-hcfc-72xm (https://github.com/sealandseacat/dbmask/security/advisories/GHSA-2jwm-hcfc-72xm). No other publicly known vulnerability has affected this project.

https://github.com/sealandseacat/dbmask/issues/new/choose — the project uses GitHub issues, with structured forms for bug reports, feature requests and adopter feedback.

GitHub Issues. https://github.com/sealandseacat/dbmask/issues

Every issue filed on this project so far has been answered and closed. Issues #6 to #12, raised by a safety review of the released 0.1.0, were fixed and closed by pull request #13 in v0.1.1; the earlier reports #1, #2 and #3 were addressed in v0.1.0. Nothing is outstanding. https://github.com/sealandseacat/dbmask/issues?q=is%3Aissue+is%3Aclosed

The one enhancement suggestion received from outside the project so far, issue #1, was accepted and shipped in v0.1.0 — it prompted the README repositioning and the use-cases and roadmap sections, with credit in the changelog. No enhancement request has gone unanswered, and a feature-request issue form is open for more.

https://github.com/sealandseacat/dbmask/issues?q=is%3Aissue — every report and its responses stay publicly readable and searchable after closing.

https://github.com/sealandseacat/dbmask/blob/main/SECURITY.md — SECURITY.md documents the reporting process, what counts as a vulnerability for this tool, the supported-versions policy, and what the reporter can expect.

Private reporting is supported two ways: GitHub private vulnerability reporting is enabled on the repository (https://github.com/sealandseacat/dbmask/security/advisories/new), and SECURITY.md gives a direct email address as a fallback for reporters who cannot use GitHub.

One vulnerability has been handled to date. It was found by a safety review of the released 0.1.0, fixed within a day, and disclosed as GHSA-2jwm-hcfc-72xm (Moderate), published on 2026-08-24 alongside the v0.1.1 release that fixes it — far inside the 14-day window. No externally submitted vulnerability reports have been received.

The project builds with the standard PEP 517 toolchain: python -m build produces the sdist and wheel from source. CI rebuilds both on every push to main and every pull request, validates the metadata with twine check --strict, installs the wheel and smoke-tests the CLI. https://github.com/sealandseacat/dbmask/blob/main/.github/workflows/ci.yml

setuptools and build — the standard Python packaging tools, configured entirely in pyproject.toml.

The build needs only FLOSS tools: CPython, setuptools, build and twine.

A pytest suite of 121 tests lives in tests/ and is released as FLOSS under the same MIT license as the project. How to run it is documented in CONTRIBUTING.md (pytest) and it is executed by CI on every push to main and every pull request. https://github.com/sealandseacat/dbmask/tree/main/tests

pytest — the standard test invocation for a Python project. Configuration lives under [tool.pytest.ini_options] in pyproject.toml.

Line coverage is 85%, with an 80% floor enforced as a blocking CI job (pytest --cov=dbmask --cov-fail-under=80). The suite exercises the CLI, the detection pipeline, every masking strategy, the seed map and the validation path end to end against throwaway SQLite databases.

GitHub Actions runs on every push to main and every pull request: ruff and mypy, the test matrix (Python 3.9-3.14 on Ubuntu plus Python 3.12 on Windows), the coverage gate, a pip-audit dependency audit, and a packaging build with a wheel smoke test. https://github.com/sealandseacat/dbmask/actions/workflows/ci.yml

CONTRIBUTING.md states it directly: "Every bug fix should come with a regression test that fails on the old code", and "Bug fix -> includes a regression test; feature -> includes tests" is a required checkbox in the pull request template. https://github.com/sealandseacat/dbmask/blob/main/CONTRIBUTING.md#pull-requests

The v0.1.1 release is the evidence: the suite grew from 46 tests at v0.1.0 to 121 at v0.1.1, in the same release that fixed issues #6 to #12 and GHSA-2jwm-hcfc-72xm, with each fix landing alongside a regression test that fails on the 0.1.0 code. https://github.com/sealandseacat/dbmask/blob/main/CHANGELOG.md

The policy is written in CONTRIBUTING.md and repeated as a checklist item in the pull request template, so contributors see it while proposing a change. https://github.com/sealandseacat/dbmask/blob/main/.github/PULL_REQUEST_TEMPLATE.md

ruff (rule sets E, F, W, I, B, UP) and mypy both run as a blocking CI job on every push to main and every pull request; configuration is in pyproject.toml. https://github.com/sealandseacat/dbmask/blob/main/.github/workflows/ci.yml

The lint job is blocking, so main stays ruff-clean and mypy-clean; a pull request that introduces a warning cannot go green. Both were verified clean at the current head of main.

The project's sole primary developer designs to the Saltzer-Schroeder principles, and 0.1.1 was an explicit application of them. Fail-safe defaults: a run without --apply is now forced to dry-run regardless of configuration, and masking aborts when the scan could not analyze every column rather than silently leaving it unmasked. Open design: the seed map never stores original values, only a salted SHA-256 digest of each original beside its masked replacement, and the full threat model — including what dbmask does not defend against, and the fact that a generated salt lives in the store alongside it unless the operator supplies one from the environment — is published at https://sealandseacat.github.io/dbmask/security-model/. Least privilege and limited attack surface: a local CLI with no network service; the LLM path is opt-in, warns before any value leaves the machine, and supports a metadata-only mode that sends column names alone. Input validation with allowlists: detection works from explicit pattern and override allowlists, and all SQL is built through SQLAlchemy Core with bound parameters. Economy of mechanism: one SQLAlchemy code path serves every supported dialect.

SQL injection: every statement is built through SQLAlchemy Core with bound parameters, never string interpolation of configuration values. Credential leakage: database URLs and the seed-map salt are supplied through environment variables and kept out of the repository, with GitHub secret scanning and push protection enabled and PyPI publishing done over OIDC so no long-lived token exists. Sensitive data in logs: previews redact original values by default behind an explicit --show-values opt-in. And the failure mode specific to this class of tool, reporting data as masked when it was not, is countered by the row-level validate step plus the 0.1.1 fixes for silently skipped primary-key columns and fail-open scans. https://sealandseacat.github.io/dbmask/security-model/

SHA-256 (FIPS 180-4) is the only cryptographic algorithm used, through Python's standard-library hashlib: masking randomness is derived from sha256(seed:value) and seed-map entries are keyed on salted SHA-256 digests. No custom or unpublished construction anywhere.

The project calls CPython's standard library (hashlib, secrets) and re-implements nothing cryptographic itself.

Everything cryptographic runs on CPython's hashlib (OpenSSL-backed) and secrets (the OS CSPRNG) — both FLOSS.

Digests are SHA-256 at 256 bits, above the NIST-through-2030 hash minimum of 224 bits, and the algorithm is not configurable. When the operator supplies no seed-map salt, dbmask generates one of 128 bits with secrets.token_hex(16). An operator-supplied salt and the masking seed are free-form secrets whose strength is the operator's choice; the CLI warns when the seed is left at the publicly known default, and the documentation tells operators to supply both from the environment.

No MD4, MD5, SHA-1, single DES or RC4 appears anywhere in the codebase; SHA-256 is the only hash in use and there is no cipher mode to choose.

No algorithm with a known serious weakness is used. There is no SHA-1 and no block-cipher mode selection in the project.

dbmask implements no network protocol and no key-agreement protocol. Transport security for database connections and optional LLM API calls is provided by the underlying drivers and HTTP client (TLS), not by this project.

dbmask does not authenticate external users and stores no passwords. Database credentials are supplied by the operator through configuration or environment variables and handed straight to the driver.

Every value dbmask generates that has to be unguessable comes from a cryptographically secure generator: the seed-map salt, when the operator does not supply one, is secrets.token_hex(16). The per-value random.Random used to produce masked output is deliberately deterministic, seeded from sha256(seed:value) — it is a reproducibility mechanism rather than a source of keys or nonces, and the consequences of that determinism are set out in the published threat model at https://sealandseacat.github.io/dbmask/security-model/.

All delivery is over HTTPS: the repository and releases from GitHub, and packages from PyPI, which pip fetches over TLS. Releases are published with PyPI Trusted Publishing (OIDC), so no long-lived API token exists to steal, and the publishing action is pinned to a commit SHA rather than a movable tag.

No hash or checksum is ever retrieved over plain http in the build or install path. pip obtains packages and their hashes from PyPI over TLS.

One vulnerability has been publicly disclosed for this project, GHSA-2jwm-hcfc-72xm (Moderate), published on 2026-08-24. The fix was already available in v0.1.1, released the same day, so the issue was never publicly known while unpatched. There are no open vulnerabilities. https://github.com/sealandseacat/dbmask/security/advisories/GHSA-2jwm-hcfc-72xm

The one vulnerability found to date was fixed within a day of being identified and shipped before its advisory was published.

No credential is committed anywhere: examples run against throwaway SQLite files and the shipped example configuration uses environment placeholders (${DB_PASSWORD}, ${OPENAI_API_KEY}), with the documentation and SECURITY.md telling operators to supply the seed-map salt the same way (salt: ${DBMASK_SEED_SALT}). GitHub secret scanning and push protection are enabled on the repository, and PyPI publishing uses OIDC rather than a stored token.

CodeQL (github/codeql-action) analyzes the Python source on every push to main, on every pull request targeting main, and weekly on a schedule; results are uploaded to GitHub code scanning and reviewed before a release is cut. ruff and mypy run on pushes to main and on pull requests as blocking jobs. Two warning-level CodeQL alerts raised during the 0.1.1 work were fixed before that release shipped (commit "fix(security): resolve both CodeQL warning-level alerts"). https://github.com/sealandseacat/dbmask/actions/workflows/codeql.yml

CodeQL's Python analysis includes its security query suite, which looks for injection, path traversal, unsafe deserialization and similar common vulnerability classes.

No exploitable vulnerability of medium or higher severity has been reported by static analysis. The two warning-level CodeQL alerts raised during the v0.1.1 work were fixed before that release shipped. The alerts open today are all note-level results from CodeQL's code-quality suite (py/should-use-with — a readability recommendation to replace a try/finally that only closes a resource with a with statement); none of them is a security finding.

On every push to main, on every pull request, and on a weekly schedule.

The pytest suite is the dynamic analysis: 121 tests execute the tool end to end against real SQLite databases, varying column types, values and configurations. Measured with pytest --cov-branch, branch coverage is 84% (456 of 544 branches), above the 80% bar, and a coverage floor runs as a blocking CI job before any release is cut.

The project is pure Python; it contains no code written in a memory-unsafe language.

The suite runs on pytest, whose assertion rewriting keeps every assertion active and reports the intermediate values on failure, and tests are never run under python -O, so Python's own assert statements stay enabled during analysis.

No medium or higher severity exploitable vulnerability has been found by dynamic analysis. The test suite is a blocking check, so failures are fixed before a change can merge.