ShareClean

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 17 Open GitHub ↗

Local-first Python CLI for safer log sharing: redact secrets, tokens, emails, and local paths before posting to GitHub issues, tickets, or AI chats.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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)
[![PyPI](https://img.shields.io/pypi/v/shareclean)](https://pypi.org/project/shareclean/)
[![Live demo](https://img.shields.io/badge/live-demo-4fd1c5)](https://omarh-creator.github.io/ShareClean/)

## Clean developer output before you share it

ShareClean is a local-first Python CLI for cleaning logs, stack traces, config snippets, terminal output, URLs, and headers **before** you paste them into a GitHub issue, Slack message, support ticket, or AI chat.

It looks for common secrets and personal details, replaces only the risky part, and keeps the useful context around it. It runs locally: no account, no API key, no network calls, and no telemetry.

```text
Before
------
DATABASE_URL=postgresql://app:fake-db-password@db.example.com/shareclean
Authorization: Bearer fake-bearer-token
callback=https://example.com/callback?token=fake-url-token&safe=1

After
-----
DATABASE_URL=postgresql://app:[REDACTED]@db.example.com/shareclean
Authorization: Bearer [REDACTED]
callback=https://example.com/callback?token=[REDACTED]&safe=1
```

[Try the browser playground](https://omarh-creator.github.io/ShareClean/) · [Install from PyPI](https://pypi.org/project/shareclean/)

![ShareClean browser playground demo](https://raw.githubusercontent.com/OmarH-creator/ShareClean/main/docs/assets/shareclean-showcase.gif)

> The playground is for trying fake text in your browser. Real use happens locally through the CLI.

## Why this exists?

Repository secret scanners are great for finding secrets that have already reached a repository. ShareClean is for the small moment before that: when you are about to paste developer output somewhere public or semi-public.

Use it when you want to share a broken log, a curl command, a config snippet, or terminal output without manually hunting through it first.

## Install

```bash
pipx install shareclean
```

Or, from a local checkout:

```bash
python -m pip install -e .
```

## Quick start

```bash
# Print cleaned output to stdout
shareclean app.log

# Write a cleaned copy
shareclean app.log --output app.cleaned.log

# Read from stdin
cat app.log | shareclean

# Get a safe metadata-only report
shareclean app.log --report
```

ShareClean never overwrites the input file in place.

## What does it help clean??

- Passwords, API keys, access tokens, client secrets, JWT-like values, SAML assertions, cookies, and webhook URLs
- Connection-string passwords and URL userinfo passwords
- `Authorization: Bearer ...` and `Authorization: Basic ...` headers
- URL query secrets such as `?token=...`
- Common secret-looking CLI arguments such as `--token` and `--password`
- Email addresses and local usernames in Windows, Linux, macOS, and WSL paths
- Private IPs, phone numbers, MAC addresses, and your own custom regex rules

See the full detector table in [Detection Rules](docs/detection-rules.md).

It aims to preserve the useful parts of the text. For example, it keeps a database host and name while replacing only the password.

## Use it in CI or a hook

Use `--check` when you want the command to fail without writing cleaned output:

```bash
shareclean app.log --check
shareclean app.log --check --fail-on severity:high
shareclean app.log --check --fail-on category:token,rule:SC004
```

`--check` returns exit code `1` only for findings selected by the check policy.

## Keep a small project policy

You can commit a `.shareclean.toml` file or add `[tool.shareclean]` to `pyproject.toml`:

```toml
redact_email = true
redact_private_ip = true
redaction_label = "[REDACTED]"
fail_on = ["severity:high"]

custom_patterns = [
  { name = "Employee ID", pattern = "EMP-[0-9]{6}", category = "credential", severity = "high" },
]
```

Useful commands:

```bash
shareclean config show
shareclean app.log --private-ip
shareclean app.log --phone
shareclean app.log --custom-pattern "EMP-[0-9]{6}"
```

Private IP, phone, and MAC redaction are enabled by default; use the corresponding `--no-*` flags if you want to turn them off.

## Safe reports, not secret previews

Reports contain rule IDs, categories, severity, locations, and replacement labels. They do **not** include matched values, source snippets, filenames, paths, hashes, or masked previews.

```bash
shareclean app.log --report
shareclean app.log --report --report-format json --explain
```

## What ShareClean is not

ShareClean is not a replacement for GitHub Secret Scanning, Gitleaks, TruffleHog, DLP, or source-history scanning. It is a practical last check for text you are about to share.

It is pattern-based, so it can miss unusual formats and can sometimes redact harmless text that resembles a secret. Treat it as a safety layer, not a guarantee.

## Help improve it

Try it with fake logs, fake configs, and fake terminal output. If it misses something or damages useful syntax, open an issue with a clearly fake reproduction. Every real failure should become a regression test.

## Development

```bash
python -m unittest discover -s tests -v
python -m compileall -q src tests
python -m build
python -m twine check dist/*
```

## License

[MIT](LICENSE)

ShareClean

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README