sharelint 5.0.0

Scan before you share.
A local, fail-closed privacy preflight for files, folders, and nested archives.
Catch secrets, PII, speaker notes, hidden sheets, and location metadata without uploading them.

Quick start · Coverage · Docs · Threat model · 简体中文

Quick start

No Python: standalone archive

Download a matching archive from a completed GitHub Release. Standalone archives include ShareLint and its Python runtime, so they do not require Python, pip, uv, or pipx on the destination computer. ShareLint 1.0.0 is available for four natively built and verified targets:

Release v0.1.2 and earlier do not contain these standalone archives. Use only files attached to a completed release, not ordinary CI artifacts. Download the archive and its same-named .sha256 file, then follow the verification and first-run instructions.

Run with uv

Alternatively, uv can obtain a compatible Python automatically. Install uv for your operating system, then run the synthetic demo without persistently installing ShareLint:

uvx sharelint demo

For regular use, install the tool persistently and make its command available to a new shell:

uv tool install sharelint
uv tool update-shell

Open a new terminal after uv tool update-shell, then run sharelint demo. In the current shell, uvx sharelint demo continues to work immediately.

If Python 3.11+ and pipx are already installed, pipx remains a supported alternative:

pipx install sharelint
sharelint demo

Preview the same synthetic scan as a self-contained local HTML report:

sharelint demo --format html --report sharelint-demo.html

A standard virtual environment and pip also work. See the OS-specific installation and troubleshooting guide for installing uv from zero, standalone archive verification, upgrades, PATH fixes, and externally managed Python environments.

For development, install from a source checkout:

git clone https://github.com/jasonzhang06-source/sharelint.git
cd sharelint
python -m pip install -e .

Platform support

You do not need to switch operating systems to use or develop ShareLint. On Ubuntu, use the Linux target or the Python package and let CI exercise the native Windows and macOS jobs. A standalone binary is specific to its listed OS and architecture, so a Windows .exe does not run on Linux; manual validation of Windows-only host behavior still requires a Windows host.

The Python 3.11+ package is tested on Ubuntu, Windows, and macOS. The standalone matrix covers the four native targets listed above. Check the CI result for the exact commit or release you use. A configured target does not imply that every filesystem, OS version, shell, locale, or security policy has been verified.

Writing reports, bundles, archives, and receipts requires hard-link support in the destination filesystem so ShareLint can preserve its no-overwrite contract. See platform support for the validation matrix, Windows notes, and filesystem limitations.

ShareLint 5.0. Add an explicit private detector pack for organization-specific markers and token prefixes, without executable plugins or arbitrary regex. Configured scans use fully hidden paths/previews and bind the detector policy into native v2 reports and pack receipts. Run sharelint staged to inspect the actual changed Git index blobs before committing, with optional pre-commit integration. It never substitutes working-tree bytes or fetches missing objects. Keep a private local review ledger with expiring decisions, aggregate reports, and a passive HTML dashboard. Review decisions never suppress findings or authorize sharing. Inspect explicitly marked Base64, hexadecimal, and percent-encoded UTF-8 text with bounded decoding and nested provenance. Encoding coverage and limits are explicit; unlabeled encodings and encoded binary documents are not covered. Review a text-redaction plan, then create a new, rescanned derivative without changing the original. Unconfigured native reports remain schema 1.0.0 and ZIP receipts remain 2.0.0; custom detector reports use schema 2.0.0. Redaction has separate plan/receipt contracts. Read the compatibility review. PDF pages and image pixels are not OCR-scanned; incomplete coverage still blocks pack.

You are about to send a ZIP. The code is clean, but the deck still has speaker notes, the workbook contains a very-hidden sheet, the PDF names its author, and an image records a location. Git-focused secret scanners do not see that entire boundary. ShareLint does.

It recursively follows a finding through nested containers, hides the matched value in every report, and says when a surface was only partially inspected. Its pack command creates a deterministic ZIP only after the configured policy and coverage checks pass, then reopens and rescans the output.

Why ShareLint

Most tools inspect one layer of a handoff. ShareLint treats the selected file, directory, and every supported nested container as one disclosure boundary:

It is intentionally composable with those controls rather than a replacement for all of them.

Demo output

The demo builds a disposable, entirely synthetic handoff bundle in a temporary directory. Its console output starts with a banner confirming that the data is synthetic and no personal files were read. It shows nested Office content, PDF metadata, active content, redacted evidence, and an explicit PDF coverage gap without touching your files. Abridged Linux output (filesystem metadata surface counts may vary by platform):

SYNTHETIC DEMO · generated sample only
No personal files were read; this run scanned only files created by ShareLint.

ShareLint 1.0.0 · local privacy preflight
INCOMPLETE · 5 policy-blocking finding(s) · 9 total · 14 surface(s)
Coverage · 13 scanned · 1 partial · 0 skipped · 0 error(s)

CRITICAL SL.SECRET.AWS_ACCESS_KEY · AWS access key identifier
         client-handoff.zip -> deck.pptx -> ppt/embeddings/clients.xlsx
         evidence <secret:20 chars> [report-scoped fingerprint]

Coverage gaps
  PARTIAL client-handoff.zip -> report.pdf · rendered-page OCR is not enabled

Original untouched · 0 bytes uploaded · matched values hidden
Incomplete means one or more listed surfaces were not fully inspected.

Found it useful? Star ShareLint, report a false positive, or request a format.

Use it

Use a repeatable policy (ShareLint 1.1+):

sharelint scan ./client-handoff --profile public
sharelint config init -o sharelint.toml
sharelint config show --config sharelint.toml --profile client

See the configuration guide. Configuration is explicit, never auto-discovered inside untrusted input.

Scan a file, directory, ZIP, or Office document:

sharelint scan ./client-handoff

Write a machine-readable report or a static HTML review:

sharelint scan ./client-handoff --format json  -o sharelint.json
sharelint scan ./client-handoff --format sarif -o sharelint.sarif
sharelint scan ./client-handoff --format html  -o sharelint.html

Report outputs are owner-only where supported, never overwrite an existing path, and must sit outside a scanned directory. demo --report follows the same rule; demo -o writes the reusable synthetic ZIP bundle and also refuses to overwrite an existing path.

Make coverage gaps fail a normal scan in automation:

sharelint scan ./client-handoff --strict --fail-on high

Create a share bundle only if it passes the fail-closed gate:

sharelint pack ./approved-files -o release.zip

On success, this writes release.zip, the minimized receipt release.zip.sharelint.json, and its exact companion report release.zip.sharelint.report.json. The receipt binds the output hash, policy, measured coverage, and companion report digest. On failure, no archive is published. An explicit --receipt blocked.json may write blocked.json plus blocked.report.json for the blocked attempt; it is never a success receipt. Companion reports include masked findings and contextual filenames, so protect them as sensitive records even though matched values remain hidden. Successful receipts use ZIP entry indices instead of repeating filenames and should still be protected.

pack always rejects partial, skipped, or errored coverage. There is deliberately no bypass flag: a pack receipt is only meaningful when every required surface was inspected.

Discover the current rule set from the installed checkout:

sharelint rules
sharelint explain SL.OFFICE.NOTES

Exit codes

sharelint demo intentionally returns 0 after rendering its synthetic blocked example.

The console and HTML report use REVIEW when a completed scan found something below the selected --fail-on threshold. That is a prompt for human review, not a blocking verdict: the exit code is still 0, and JSON/SARIF keep summary.verdict: "pass" for the stable automation contract. PASS means no findings were retained; neither label is a guarantee that the input is safe.

What it checks

Run sharelint rules for the installed rule registry and read Rules and identifiers for stability and severity semantics.

Designed around the share boundary

files / folders / nested containers
                 │
                 ▼
        bounded local traversal
                 │
       ┌─────────┼──────────┐
       ▼         ▼          ▼
    secrets   document   coverage
      + PII    surfaces     gaps
       └─────────┼──────────┘
                 ▼
       privacy-safe findings
                 │
          scan ──┴── pack gate
                         │ pass only
                         ▼
               deterministic ZIP
                  + hash receipt
                  + output rescan

The core scan path has no network feature, telemetry, or runtime dependency outside Python's standard library. It does not execute macros or JavaScript, invoke Office/PDF applications, follow external relationships, or extract archive members to disk.

The architecture guide maps these guarantees to module boundaries and documents safe extension points for contributors.

Findings carry a nested logical source chain such as:

handoff.zip -> deck.pptx -> ppt/embeddings/customers.xlsx -> xl/workbook.xml

Matched evidence is reduced immediately to a type-aware mask and a keyed, report-scoped fingerprint. The ephemeral HMAC key is never serialized, so the fingerprint cannot be used as a stable cross-report identifier. Reports are still sensitive because filenames, structure, finding types, and counts can reveal context.

What ShareLint does not promise

ShareLint is a preflight, not a proof system. A pass means only that no configured blocker was found on the surfaces listed in that report under that policy.

• It cannot guarantee that a bundle is safe, anonymous, compliant, or free of sensitive data.
• It does not currently OCR PDF pages or image pixels.
• It never modifies originals. Text redaction creates a separately reviewed derivative; other formats need manual fixes in a copy.
• It cannot determine whether a detected credential is live or whether personal data was intended.
• Unsupported, encrypted, malformed, or budget-limited content remains a visible coverage gap.

The security boundary and residual risks are documented in the threat model. Machine-output consumers should use the report and receipt contract, not parse console text. JSON Schema files for automated validation live in schemas/.

Verify a delivered bundle offline

sharelint verify release.zip --receipt release.zip.sharelint.json --report release.zip.sharelint.report.json

Version 1.2 checks exact report/archive bytes, recomputed report summaries, recorded policy settings, and ZIP file manifests. It does not upload or extract files. Integrity is not a signature, producer authentication, a new privacy scan, or a guarantee of safe sharing. See the verification contract for blocked receipts, independent digest pinning, budgets, and exit codes.

Review what changed

sharelint diff before.json after.json
sharelint diff before.json after.json --format html -o comparison.html

Version 1.3 compares rule/severity counts and coverage. It flags increased blockers, incomplete coverage, reduced inspection, and changed settings for review. It never treats report-scoped fingerprints as stable evidence IDs, and fewer findings do not prove a particular issue was fixed. See the comparison guide.

Review before export

sharelint plan create ./handoff -o handoff.plan.json
sharelint plan inspect handoff.plan.json
sharelint pack ./handoff -o delivery.zip --plan handoff.plan.json

Packing repeats all strict checks and rejects changed source, policy, or scan snapshots. A plan is a private review record, not approval or a signature. See handoff plans.

Check several handoffs

sharelint batch ./handoff-a ./handoff-b --format html -o batch.html

Each input has a separate result and shares a finite inspection-byte budget. Failures and unattempted targets remain visible; aggregate output uses input-order IDs, not filenames. See batch preflight.

Create a reviewed text derivative

sharelint redact plan private.log --name public.log -o redaction.plan.json
sharelint redact inspect redaction.plan.json
sharelint redact apply private.log --plan redaction.plan.json -o public.log

UTF-8 text only, bounded to 4 MiB. Plans contain positions and rules, not original text. The source is rechecked and a reopened output rescan must have complete coverage and no known findings before publication. Private-key blocks and document/image containers are not automatically cleaned. See text derivatives.

Keep a private review history

sharelint review init private-review
sharelint review import private-review --report scan.json
sharelint review decide private-review r000001 --decision needs-fix --reason confirmed-finding --reviewer operator-1
sharelint review list private-review --format html -o review.html
sharelint review verify private-review

Import an existing native scan report; the workspace keeps counts and hashes, not its filenames, matched evidence, or prose. Decisions are append-only; risk-acceptance and false-positive decisions require a future expiry. Original scan verdicts remain visible and unchanged. No local server is started. See review workspaces for byte limits, trusted-tip verification, permissions, and recovery boundaries.

Project status and direction

ShareLint adds explicit policy profiles, offline receipt verification, report comparison, batch checks, handoff plans, reviewed UTF-8 text derivatives, and private review workspaces to the scanning/packaging workflow. The maintenance priority is synthetic regression tests, conservative coverage, and compatibility. Local OCR, policy exceptions, pre-send hooks, and a desktop interface remain future work. See the roadmap.

The project stays useful by keeping three promises measurable: input remains local, evidence remains hidden, and incomplete coverage never masquerades as a clean scan.

Help shape the next release

The most useful early feedback is a real sharing workflow described with synthetic data: a format that ShareLint cannot inspect yet, a false positive that can be reproduced safely, or a report that was hard to act on. Open a focused feature request or bug report. If ShareLint fits a problem you care about, starring the repository helps more people discover it.

Contributing and security

Issues and pull requests are welcome, especially for narrowly scoped format coverage, synthetic regression fixtures, false-positive reductions, and hostile-input tests. Start with CONTRIBUTING.md and never attach real secrets or personal documents.

Report a possible vulnerability privately through GitHub's Security → Report a vulnerability flow, as described in SECURITY.md. General help is covered by SUPPORT.md; project decisions follow GOVERNANCE.md.

License

MIT © ShareLint contributors.