Skip to content

Publication checks and private audits

The repository’s SECURITY.md distinguishes private deployment data from credentials and intentional public attribution. These checks are bounded review aids, not proof that every possible disclosure has been eliminated.

What each check proves

Check Scope and inputs Does not establish
scripts/check-secrets.sh Credential-like filenames and existing credential string patterns in Git publication candidates All credential formats, active/revoked status, general privacy
scripts/check-publication.py Same credential checks plus private-storage and selected example/artifact rules Approval for every unknown identity, clean history or publication readiness
--staged Exact Git index blobs, including files whose working copies differ Unstaged changes or historical objects
--artifact-root DIR Nonarchive bytes and filenames in explicitly selected output trees instead of Git inputs Archive expansion, image/OCR meaning, runtime behavior
External private manifest Scoped exact matches for known sensitive values and filenames Unknown private values, semantic equivalence, Git author/committer metadata
Historical audit Separately inventory retained refs, raw blobs, messages and author/committer fields Removal from tags, releases, Actions, caches or other clones
Retained GitHub review Separately inspect accessible logs, artifacts, caches and publication surfaces Surfaces not fetched or inaccessible copies
Release qualification Existing exact-source, architecture, installed and artifact gates Privacy cleanup or historical removal

Without --staged, source checks read tracked working copies plus nonignored untracked source. Untracked build/cache/dependency directories are outside that scope; inspect selected generated outputs explicitly. Tracked files remain in scope even if an ignore rule now matches them. The scanner reads nonarchive bytes; it does not open archives or decode images. Archives and LFS pointers are counted but their payloads are not read; required private audits report incomplete for these. Submodule payloads also require a separate audit.

Exit statuses are 0 for a clean selected scope, 1 for findings, and 2 for incomplete inspection or unavailable/invalid required inputs. A public check can return 0 while explicitly reporting private matching NOT RUN. --require-private cannot silently pass without a usable manifest.

Narrow public rules and exceptions

  • Private configuration/storage paths and copied .git metadata must not be publication inputs. Ignored local configuration is neither scanned nor modified; force-tracking it fails. Symlinks must resolve within the selected public inputs, not private storage.
  • Public profiles/*/etc/rfsentry/appliance.conf.example identities and issuance ranges use reserved example domains and documentation networks. Loopback is permitted. The deliberate short aliases pi4-radio, pi5-radio and example-radio are narrow local examples, not globally reserved names or permission for arbitrary personal host aliases. They require customization.
  • Public hardware profiles use the project example namespace 90000000 through 90000099; serial filenames must match their declarations. Wildcard spur selectors are permitted. Existing configuration/routing checks still own relationship and device-policy validation. These rules never constrain an installed/private hardware profile selected by the supported installer.
  • The checked-in macOS identity defaults use the project namespace. Users can override their own saved private configuration as documented; deployed identifiers are not silently migrated by this check.
  • NRSC-5 WASM/source maps must not contain account home prefixes. The hosted Emscripten loader's virtual /home/web_user is not an operator home directory; the binary/map rule does not apply to that upstream runtime string.
  • Public certificates and public keys are allowed; private-key headers and private credential bundles are flagged. .env.example is a filename exception, not an exemption from credential-content checks.
  • Five reviewed credential-assignment lines in four existing browser tests are pinned by exact line hashes in the checker. They are isolated mocks/loopback fixture credentials or a random-generation prefix, not deployment credentials. A changed line requires fresh review. The exception applies only to the assignment heuristic; it never suppresses token/private-key patterns or private exact matching, and never exempts the rest of a test file.
  • There are no universal IP, email, URL, coordinate, serial or hash bans. Official datasets, vendor attribution, synthetic protocol data and approved CI metadata remain usable. Unknown identifying content still needs review.

Diagnostics give a category and relative file location (masked when the path itself carries protected content). They never echo matched values, source lines, private manifest content or raw exception messages. An input ordinal distinguishes masked paths. Review the affected content locally on a trusted machine.

Trusted private exact matching

Never provide private values to contributor PR code or ordinary CI hooks. There is no environment-variable auto-discovery of the manifest. A private run requires an explicitly selected, reviewed checker copy outside the audited checkout, using Python isolated mode. The manifest must be owner-only, outside both the repository and every selected artifact root. Do not store it in config/local/: that location is supported for deployment inputs, not for exact-match audit maps.

Illustrative manifest shape (only synthetic values shown):

{
  "schemaVersion": 1,
  "approvedPublicEmails": ["maintainer@example.net"],
  "rules": [
    {"category": "hardware", "value": "SYNTHETIC_PRIVATE_SENTINEL", "paths": ["profiles/**", "test/**"]}
  ]
}

Rules accept literal strings, optional ASCII ignoreCase, and repository-relative path globs. Categories are network, identity, location, hardware, operational and credential. No executable expressions or manifest regexes are evaluated. Scope geographic/address rules to their actual fixture contexts; do not ban a public dataset merely because it contains the same locality.

Approved public emails are exact address exceptions, not domain/file exemptions: a private hostname elsewhere on the same line/file still fails. Keep the owner's explicitly approved email in this list when a private-domain rule overlaps it. Other contributor attribution must retain its own reviewed scope; do not turn a personal-data inventory into a blanket author-replacement policy.

Example operator workflow, after reviewing the checker and choosing private paths outside the checkout and upload/cache roots:

# Replace these two paths with owner-only private locations.
TRUSTED_CHECKER=/private/audit/check-publication.py
PRIVATE_INPUT=/private/audit/exact-values.json
# Copy the reviewed checker there and record its digest privately before use.
python3 -I "$TRUSTED_CHECKER" --root "$PWD" \
  --private-input "$PRIVATE_INPUT" --require-private
python3 -I "$TRUSTED_CHECKER" --root "$PWD" \
  --artifact-root components/rfsentry-web/dist/docs \
  --private-input "$PRIVATE_INPUT" --require-private

Check each selected generated surface deliberately. For example, a generated gzip sitemap or old package archive leaves required private coverage incomplete; this scanner does not open it. Inspect or regenerate such outputs separately within the authorized publication scope. No default scanner report or private file is written into the repository. If redirecting diagnostics, use private storage as well. Empty artifact selections and missing, malformed, overly permissive, in-checkout or overlapping input files return incomplete rather than falling back to a pass. A trusted copy only reads Git blobs/files; it does not import or run checkout modules, hooks, filters, tests or build scripts. Git filesystem-monitor hooks are disabled for its read-only Git operations.

Storage and publication boundaries

Supported real configuration locations are /etc/rfsentry/, /etc/rtl_tcp/, private --appliance-config/--profile-dir inputs and the client's per-user configuration. config/local/ is ignored. Public validation passes each checked-in identity example explicitly to profile checks, avoiding fallback to installed identity during those checks. None of these private locations is an input to the current package builders or documentation generator.

Client packages copy named binaries/icons into a clean staging directory. Server installed-source bundles select tracked test directories and an explicit script allowlist, excluding config/local/. Documentation builds from documentation/. Workflow uploads name build/bundle/evidence directories rather than the private configuration roots or the whole checkout. Existing installed qualification evidence collection rejects symlinks. These are scoped publication boundaries, not permission to place audit files in a broadly uploaded evidence or distribution directory. Review any future collector/output-path change.

Existing diagnostics may describe live operator data. Keep raw captures and unredacted diagnostic outputs private; do not assume every operational log is safe to upload. Current source checks do not inspect retained Actions payloads, old release assets or other repositories/clones.

A release handoff must separately account for backup verification, authorized history rewriting, retained branch selection, metadata transformations, old-clone and automation coordination, GitHub-surface review, fresh artifact qualification, and operator-owned old tag/release retirement. The project's current cleanup has separately authorized Step 7; that one-time instruction is not permanent permission to rewrite arbitrary history.

After a coordinated rewrite, follow the history and clone transition guide.