shareclean 0.2.0__tar.gz

shareclean-0.2.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to ShareClean will be documented in this file.
+
+This project follows a simple release format inspired by Keep a Changelog and uses semantic versioning for public releases.
+
+## 0.2.0 - 2026-07-02
+
+### Added
+
+- Stable `SC###` detector IDs, categories, severities, and 1-based location ranges.
+- Versioned JSON report schema `1.0` with privacy-preserving `source` labels.
+- `--fail-on` and `--ignore-for-check` selectors for CI check policies.
+- Project config support for `pyproject.toml` and `.shareclean.toml`, including profiles and environment variable overrides.
+- `shareclean config show` for inspecting effective non-sensitive configuration.
+- PEM private-key block detection.
+- Fake-secret fixture corpus with manifest-driven regression tests.
+- GitHub Release workflow for TestPyPI and PyPI Trusted Publishing without long-lived API tokens.
+
+### Changed
+
+- Bumped package and CLI version to `0.2.0`.
+- `pipx install shareclean` is now the intended install path after PyPI publication.
+- Reports no longer include filenames or full input paths by default.
+- Overlapping detections now emit one finding by severity and detector specificity.
+- `--no-email` is now a deprecated alias for `--no-redact-email`.
+
+### Verified
+
+- PyPI and TestPyPI package-name preflight returned 404 for `shareclean` on 2026-07-02, so the planned public package name appeared available before release workflow implementation.
+
+## 0.1.1 - 2026-07-01
+
+### Added
+
+- `--redaction-label TEXT` for customizing the generic `[REDACTED]` label used by passwords, API keys, Bearer tokens, and connection string passwords.
+- Interactive playground support for trying custom redaction labels in the browser demo.
+
+## 0.1.0 - 2026-07-01
+
+### Added
+
+- Standard-library-only `shareclean` CLI.
+- Redaction rules for key-value secrets, connection string passwords, Bearer tokens, JWT-like tokens, email addresses, local user paths, and opt-in private IP addresses.
+- Human-readable and JSON reports that exclude original secret values.
+- `--check`, `--output`, `--report`, `--report-format`, `--no-email`, and `--redact-private-ip` CLI options.
+- Unit, integration, fixture-based, and property-style tests.
+- Cross-platform line-ending preservation for file, stdin, and stdout workflows.
+- GitHub-ready documentation, CI, security policy, and contribution guide.

shareclean-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,23 @@
+# Code of Conduct
+
+ShareClean aims to be a practical, respectful project for developers who care about safer debugging and sharing workflows.
+
+## Expected Behavior
+
+- Be respectful and constructive.
+- Assume good intent, but be clear when something is unsafe or incorrect.
+- Use fake examples when discussing secrets, credentials, logs, or customer data.
+- Keep feedback focused on the work and its impact.
+
+## Unacceptable Behavior
+
+- Harassment, insults, threats, or discriminatory language.
+- Posting real credentials, private logs, personal data, or customer data.
+- Publicly disclosing a suspected vulnerability before the maintainer has had a reasonable chance to respond.
+- Repeatedly derailing technical discussions.
+
+## Reporting
+
+For conduct concerns, open a minimal issue asking for maintainer contact without posting private details.
+
+For security concerns, follow [SECURITY.md](SECURITY.md).

shareclean-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing
+
+Thanks for helping make ShareClean safer and more useful.
+
+## Development Setup
+
+```bash
+git clone https://github.com/OmarH-creator/ShareClean.git
+cd ShareClean
+python -m pip install -e .
+python -m unittest discover -s tests -v
+```
+
+No third-party runtime or test dependencies are required.
+
+## Project Principles
+
+- Keep ShareClean local-first: no network calls, accounts, telemetry, or remote scanning.
+- Preserve debugging context wherever possible. Redact the sensitive value, not the whole line.
+- Never store or print original matched secret values in `Finding`, reports, exceptions, or test output.
+- Use clearly fake test values only.
+- Prefer precise, readable standard-library code over broad dependencies.
+- Add tests for every detector or behavior change.
+
+## Adding Or Changing A Detector
+
+1. Add or update the rule in `src/shareclean/detectors.py`.
+2. Keep rule order intentional. More specific rules should run before broader rules.
+3. Add positive and negative detector tests.
+4. Add redactor or property-style tests when behavior spans multiple modules.
+5. Confirm reports never include the raw matched value.
+
+Run:
+
+```bash
+python -m unittest discover -s tests -v
+python -m compileall -q src tests
+```
+
+## Pull Request Checklist
+
+- Tests pass locally.
+- New behavior is covered by tests.
+- Documentation is updated when CLI behavior or detection behavior changes.
+- Examples use fake values only.
+- The PR does not add telemetry, network behavior, or unnecessary dependencies.
+
+## Security Issues
+
+Do not put real secrets or production logs in GitHub issues or pull requests. Read [SECURITY.md](SECURITY.md) first.

shareclean-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omar Hassan Elsayed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shareclean-0.2.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include SECURITY.md
+include CONTRIBUTING.md
+include CODE_OF_CONDUCT.md
+include ROADMAP.md
+recursive-include docs *.md
+recursive-include docs/assets *.svg
+recursive-include tests *.py
+recursive-include tests/fixtures *.txt *.json *.env *.log *.yml

shareclean-0.2.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: shareclean
+Version: 0.2.0
+Summary: Local-first CLI for sanitizing logs, stack traces, and text before sharing.
+Author: Omar Hassan Elsayed
+License-Expression: MIT
+Project-URL: Homepage, https://omarh-creator.github.io/ShareClean/
+Project-URL: Repository, https://github.com/OmarH-creator/ShareClean
+Project-URL: Documentation, https://omarh-creator.github.io/ShareClean/
+Project-URL: Issues, https://github.com/OmarH-creator/ShareClean/issues
+Project-URL: Changelog, https://github.com/OmarH-creator/ShareClean/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/OmarH-creator/ShareClean/security
+Keywords: cli,logs,privacy,redaction,security,secrets
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Text Processing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2; python_version < "3.11"
+Dynamic: license-file
+
+# ShareClean
+
+[![CI](https://github.com/OmarH-creator/ShareClean/actions/workflows/ci.yml/badge.svg)](https://github.com/OmarH-creator/ShareClean/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+[![Release](https://img.shields.io/github/v/release/OmarH-creator/ShareClean)](https://github.com/OmarH-creator/ShareClean/releases)
+[![Live demo](https://img.shields.io/badge/live-demo-4fd1c5)](https://omarh-creator.github.io/ShareClean/)
+
+Local-first Python CLI for sanitizing logs, stack traces, config snippets, and terminal output before you paste them into GitHub issues, support tickets, Slack, or AI chats.
+
+ShareClean detects common sensitive values, replaces only the risky portion, and reports safe metadata without storing or printing the original secret. It makes no network calls and sends no telemetry.
+
+[Try the interactive browser playground](https://omarh-creator.github.io/ShareClean/) to see the redaction rules before installing.
+
+![ShareClean browser playground demo](docs/assets/shareclean-showcase.gif)
+
+Browser playground shown for illustration; real workflows run locally through the CLI.
+
+## Install
+
+With `pipx`:
+
+```bash
+pipx install shareclean
+```
+
+From a local checkout:
+
+```bash
+python -m pip install -e .
+```
+
+Run without installing from the repository root:
+
+```bash
+python -m shareclean --help
+```
+
+## Quick Start
+
+```bash
+shareclean app.log
+shareclean app.log --output app.cleaned.log
+shareclean app.log --report
+shareclean app.log --report --report-format json
+shareclean app.log --check
+shareclean app.log --check --fail-on severity:high
+shareclean app.log --check --fail-on category:token,rule:SC004
+shareclean app.log --check --ignore-for-check category:pii_email
+```
+
+`--check` exits `1` only for findings selected by the check policy and never writes sanitized text to stdout.
+
+## Configuration
+
+ShareClean supports committed project policy in either `pyproject.toml` or `.shareclean.toml`.
+
+```toml
+[tool.shareclean]
+redact_email = true
+redact_private_ip = false
+redaction_label = "[REDACTED]"
+profile = "default"
+
+[tool.shareclean.profiles.ci]
+redact_email = true
+redact_private_ip = true
+fail_on = ["severity:high"]
+```
+
+For `.shareclean.toml`, omit the `tool.shareclean` prefix:
+
+```toml
+redact_email = true
+redact_private_ip = false
+
+[profiles.ci]
+redact_private_ip = true
+fail_on = ["severity:high"]
+```
+
+Config location:
+
+1. `--config PATH`
+2. Nearest project directory containing `.shareclean.toml` or a `pyproject.toml` with `[tool.shareclean]`
+3. Defaults
+
+Auto-discovery walks upward from the current directory until the Git root or filesystem root. It uses only the nearest config directory and never merges parent configs. If `.shareclean.toml` and ShareClean config in `pyproject.toml` exist in the same selected directory, ShareClean exits `2`.
+
+Config precedence:
+
+1. CLI flags
+2. Environment variables
+3. Selected profile values
+4. Base project config
+5. Defaults
+
+Environment variables:
+
+- `SHARECLEAN_REDACT_EMAIL`
+- `SHARECLEAN_REDACT_PRIVATE_IP`
+- `SHARECLEAN_REDACTION_LABEL`
+- `SHARECLEAN_PROFILE`
+- `SHARECLEAN_FAIL_ON`
+- `SHARECLEAN_IGNORE_FOR_CHECK`
+
+Boolean environment values accept `true`, `1`, `yes`, `on`, `false`, `0`, `no`, and `off`.
+
+Inspect effective configuration without reading input:
+
+```bash
+shareclean config show
+```
+
+## Detection Rules
+
+| Rule ID | Detector | Category | Severity |
+|---|---|---|---|
+| `SC001` | Key-value secret | `credential` | `high` |
+| `SC002` | Bearer token | `token` | `high` |
+| `SC003` | JWT-like token | `token` | `high` |
+| `SC004` | Connection-string password | `connection_string` | `critical` |
+| `SC005` | Email address | `pii_email` | `medium` |
+| `SC006` | Local user path | `pii_path` | `medium` |
+| `SC007` | Private IP address | `internal_network` | `medium` |
+| `SC008` | PEM private-key block | `private_key` | `critical` |
+
+Private IP detection is off by default; enable it with `--redact-private-ip` or config.
+
+When detectors overlap on the same text range, ShareClean emits one finding using the highest-severity rule. If severities match, it uses the most specific detector.
+
+## JSON Reports
+
+JSON reports use schema version `1.0` and do not include filenames, paths, matched values, hashes, source snippets, or masked previews.
+
+```json
+{
+  "schema_version": "1.0",
+  "source": "file",
+  "summary": {
+    "findings": 1,
+    "by_category": {
+      "credential": 1
+    },
+    "by_severity": {
+      "high": 1
+    }
+  },
+  "findings": [
+    {
+      "rule_id": "SC001",
+      "category": "credential",
+      "severity": "high",
+      "location": {
+        "start": {
+          "line": 1,
+          "column": 10
+        },
+        "end": {
+          "line": 1,
+          "column": 27
+        }
+      },
+      "replacement": "[REDACTED]"
+    }
+  ]
+}
+```
+
+Locations are 1-based. End positions are exclusive. Columns count Unicode code points after treating CRLF as one LF newline for location purposes.
+
+## CLI Reference
+
+```text
+usage: shareclean [-h] [--version] [--check] [--output FILE] [--report]
+                  [--report-format {text,json}] [--config FILE]
+                  [--profile NAME] [--redact-email] [--no-redact-email]
+                  [--redact-private-ip] [--no-redact-private-ip]
+                  [--redaction-label TEXT] [--fail-on SELECTORS]
+                  [--ignore-for-check SELECTORS]
+                  [FILE]
+```
+
+`--no-email` remains as a deprecated alias for `--no-redact-email`.
+
+Exit codes:
+
+| Code | Meaning |
+|---:|---|
+| `0` | Completed successfully |
+| `1` | Selected findings detected in `--check` mode |
+| `2` | User, I/O, config, or selector error |
+| `3` | Unexpected internal error |
+
+## Safety Model
+
+ShareClean is intentionally local and transparent:
+
+- No network calls
+- No cloud processing
+- No telemetry
+- No account or API key required
+- Original matched secret values are not stored in findings or reports
+- Input files are never modified in place
+
+## Coverage And Limitations
+
+ShareClean is pattern-based. It can miss unusual formats and can redact benign text that resembles a secret. It is not a replacement for repository secret scanners, source-history scanning, or DLP systems.
+
+The test corpus under `tests/fixtures/` uses only fake values and is split into generic, cloud, database, CI/CD, SaaS, log, YAML/JSON/env, and false-positive packs. Bug reports that change detection should add a regression fixture using clearly fake data.
+
+## Development
+
+Run the test suite:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+Run packaging checks:
+
+```bash
+python -m compileall -q src tests
+python -m build
+python -m twine check dist/*
+```
+
+## License
+
+ShareClean is released under the [MIT License](LICENSE).

shareclean-0.2.0/README.md

@@ -0,0 +1,230 @@
+# ShareClean
+
+[![CI](https://github.com/OmarH-creator/ShareClean/actions/workflows/ci.yml/badge.svg)](https://github.com/OmarH-creator/ShareClean/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+[![Release](https://img.shields.io/github/v/release/OmarH-creator/ShareClean)](https://github.com/OmarH-creator/ShareClean/releases)
+[![Live demo](https://img.shields.io/badge/live-demo-4fd1c5)](https://omarh-creator.github.io/ShareClean/)
+
+Local-first Python CLI for sanitizing logs, stack traces, config snippets, and terminal output before you paste them into GitHub issues, support tickets, Slack, or AI chats.
+
+ShareClean detects common sensitive values, replaces only the risky portion, and reports safe metadata without storing or printing the original secret. It makes no network calls and sends no telemetry.
+
+[Try the interactive browser playground](https://omarh-creator.github.io/ShareClean/) to see the redaction rules before installing.
+
+![ShareClean browser playground demo](docs/assets/shareclean-showcase.gif)
+
+Browser playground shown for illustration; real workflows run locally through the CLI.
+
+## Install
+
+With `pipx`:
+
+```bash
+pipx install shareclean
+```
+
+From a local checkout:
+
+```bash
+python -m pip install -e .
+```
+
+Run without installing from the repository root:
+
+```bash
+python -m shareclean --help
+```
+
+## Quick Start
+
+```bash
+shareclean app.log
+shareclean app.log --output app.cleaned.log
+shareclean app.log --report
+shareclean app.log --report --report-format json
+shareclean app.log --check
+shareclean app.log --check --fail-on severity:high
+shareclean app.log --check --fail-on category:token,rule:SC004
+shareclean app.log --check --ignore-for-check category:pii_email
+```
+
+`--check` exits `1` only for findings selected by the check policy and never writes sanitized text to stdout.
+
+## Configuration
+
+ShareClean supports committed project policy in either `pyproject.toml` or `.shareclean.toml`.
+
+```toml
+[tool.shareclean]
+redact_email = true
+redact_private_ip = false
+redaction_label = "[REDACTED]"
+profile = "default"
+
+[tool.shareclean.profiles.ci]
+redact_email = true
+redact_private_ip = true
+fail_on = ["severity:high"]
+```
+
+For `.shareclean.toml`, omit the `tool.shareclean` prefix:
+
+```toml
+redact_email = true
+redact_private_ip = false
+
+[profiles.ci]
+redact_private_ip = true
+fail_on = ["severity:high"]
+```
+
+Config location:
+
+1. `--config PATH`
+2. Nearest project directory containing `.shareclean.toml` or a `pyproject.toml` with `[tool.shareclean]`
+3. Defaults
+
+Auto-discovery walks upward from the current directory until the Git root or filesystem root. It uses only the nearest config directory and never merges parent configs. If `.shareclean.toml` and ShareClean config in `pyproject.toml` exist in the same selected directory, ShareClean exits `2`.
+
+Config precedence:
+
+1. CLI flags
+2. Environment variables
+3. Selected profile values
+4. Base project config
+5. Defaults
+
+Environment variables:
+
+- `SHARECLEAN_REDACT_EMAIL`
+- `SHARECLEAN_REDACT_PRIVATE_IP`
+- `SHARECLEAN_REDACTION_LABEL`
+- `SHARECLEAN_PROFILE`
+- `SHARECLEAN_FAIL_ON`
+- `SHARECLEAN_IGNORE_FOR_CHECK`
+
+Boolean environment values accept `true`, `1`, `yes`, `on`, `false`, `0`, `no`, and `off`.
+
+Inspect effective configuration without reading input:
+
+```bash
+shareclean config show
+```
+
+## Detection Rules
+
+| Rule ID | Detector | Category | Severity |
+|---|---|---|---|
+| `SC001` | Key-value secret | `credential` | `high` |
+| `SC002` | Bearer token | `token` | `high` |
+| `SC003` | JWT-like token | `token` | `high` |
+| `SC004` | Connection-string password | `connection_string` | `critical` |
+| `SC005` | Email address | `pii_email` | `medium` |
+| `SC006` | Local user path | `pii_path` | `medium` |
+| `SC007` | Private IP address | `internal_network` | `medium` |
+| `SC008` | PEM private-key block | `private_key` | `critical` |
+
+Private IP detection is off by default; enable it with `--redact-private-ip` or config.
+
+When detectors overlap on the same text range, ShareClean emits one finding using the highest-severity rule. If severities match, it uses the most specific detector.
+
+## JSON Reports
+
+JSON reports use schema version `1.0` and do not include filenames, paths, matched values, hashes, source snippets, or masked previews.
+
+```json
+{
+  "schema_version": "1.0",
+  "source": "file",
+  "summary": {
+    "findings": 1,
+    "by_category": {
+      "credential": 1
+    },
+    "by_severity": {
+      "high": 1
+    }
+  },
+  "findings": [
+    {
+      "rule_id": "SC001",
+      "category": "credential",
+      "severity": "high",
+      "location": {
+        "start": {
+          "line": 1,
+          "column": 10
+        },
+        "end": {
+          "line": 1,
+          "column": 27
+        }
+      },
+      "replacement": "[REDACTED]"
+    }
+  ]
+}
+```
+
+Locations are 1-based. End positions are exclusive. Columns count Unicode code points after treating CRLF as one LF newline for location purposes.
+
+## CLI Reference
+
+```text
+usage: shareclean [-h] [--version] [--check] [--output FILE] [--report]
+                  [--report-format {text,json}] [--config FILE]
+                  [--profile NAME] [--redact-email] [--no-redact-email]
+                  [--redact-private-ip] [--no-redact-private-ip]
+                  [--redaction-label TEXT] [--fail-on SELECTORS]
+                  [--ignore-for-check SELECTORS]
+                  [FILE]
+```
+
+`--no-email` remains as a deprecated alias for `--no-redact-email`.
+
+Exit codes:
+
+| Code | Meaning |
+|---:|---|
+| `0` | Completed successfully |
+| `1` | Selected findings detected in `--check` mode |
+| `2` | User, I/O, config, or selector error |
+| `3` | Unexpected internal error |
+
+## Safety Model
+
+ShareClean is intentionally local and transparent:
+
+- No network calls
+- No cloud processing
+- No telemetry
+- No account or API key required
+- Original matched secret values are not stored in findings or reports
+- Input files are never modified in place
+
+## Coverage And Limitations
+
+ShareClean is pattern-based. It can miss unusual formats and can redact benign text that resembles a secret. It is not a replacement for repository secret scanners, source-history scanning, or DLP systems.
+
+The test corpus under `tests/fixtures/` uses only fake values and is split into generic, cloud, database, CI/CD, SaaS, log, YAML/JSON/env, and false-positive packs. Bug reports that change detection should add a regression fixture using clearly fake data.
+
+## Development
+
+Run the test suite:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+Run packaging checks:
+
+```bash
+python -m compileall -q src tests
+python -m build
+python -m twine check dist/*
+```
+
+## License
+
+ShareClean is released under the [MIT License](LICENSE).

shareclean-0.2.0/ROADMAP.md

@@ -0,0 +1,22 @@
+# Roadmap
+
+ShareClean is intentionally small: local-first, standard-library-only, and focused on making text safer to share. These are the most likely next improvements.
+
+## Near Term
+
+- Add more targeted detectors for common cloud and SaaS token shapes while keeping examples fake.
+- Add optional allowlist support for values users intentionally want to preserve.
+- Add optional SARIF output for code-scanning style integrations.
+- Add repository-relative source paths as an explicit opt-in report mode for CI.
+- Add `--report-format jsonl` for batch and stream processing.
+
+## Maybe Later
+
+- More fixture packs for common log formats.
+
+## Non-Goals
+
+- No telemetry.
+- No network scanning.
+- No credential validation against external services.
+- No claim that ShareClean replaces dedicated secret scanners such as repository scanners or data loss prevention systems.