Metadata-Version: 2.4
Name: pyl-secret-leaks
Version: 0.5.2
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Rust
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Summary: pyl — fast secret scanner for your codebase
Keywords: security,secrets,scanner,sast,devops
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# pyl

> **pyl** — fast secret scanner for your codebase


A lightweight, zero-config secret scanner written in Rust — available as CLI tool **and** Python library. Scans source code for accidentally committed secrets, credentials, and sensitive data.

---

## Features

- **89 built-in detection rules** covering cloud providers, LLMs, databases, HTTP auth, and more
- **Multiple output formats** — pretty-printed, JSON, and SARIF
- **GitHub Actions integration** — writes a formatted Job Summary to `$GITHUB_STEP_SUMMARY`
- **Inline suppression** — annotate lines with `# pyl-ignore` to silence known false positives
- **Configurable** via `pyl.toml` — restrict file extensions, exclude paths, disable rules
- **Sorted output** — findings ordered by severity (CRITICAL → HIGH → MEDIUM → LOW → WARNING), then by file and line
- **Smart false-positive filtering** — skips template variables, shell variables, and attribute references
- **Binary-safe** — skips non-text files automatically
- **Respects `.env` files** — always excluded from scanning

---

## Installation

### From source

```bash
git clone https://github.com/YOUR_USERNAME/pyl.git
cd pyl
cargo install --path .
```

### via pip

```bash
pip install pyl-secret-leaks
pyl check .
```

### Pre-built binaries

Download the latest binary for your platform from the [Releases](https://github.com/YOUR_USERNAME/pyl/releases/latest) page:

| Platform | File |
|----------|------|
| Linux x86_64 | `pyl-linux-amd64` |
| Linux ARM64 | `pyl-linux-arm64` |
| Windows x86_64 | `pyl-windows-amd64.exe` |
| macOS Apple Silicon | `pyl-macos-arm64` |

```bash
# Linux / macOS — make executable and move to PATH
chmod +x pyl-linux-amd64
sudo mv pyl-linux-amd64 /usr/local/bin/pyl
```

---

## Python Library

After installing via `pip install pyl-secret-leaks`, you can use pyl directly from Python — e.g. to scan text before sending it to an LLM:

```python
from pyl import scan_text

findings = scan_text("My API key is sk-proj-abc123xyz...")
for f in findings:
    print(f.rule_id, f.severity, f.secret)

# Disable specific rules:
findings = scan_text(text, disable_rules=["http-insecure-url"])
```

Each finding has the attributes: `rule_id`, `description`, `severity`, `line_number`, `line`, `secret`, `tags`.

---

## CLI Usage

```bash
# Scan the current directory
pyl check

# Scan a specific path
pyl check --source ./src

# JSON output (e.g. for piping)
pyl check --format json

# SARIF output (e.g. for GitHub Code Scanning)
pyl check --format sarif

# Verbose mode (shows every file scanned/skipped)
pyl check --verbose

# Include WARNING-level findings in detail output
pyl check --warnings

# Limit file size (default: 1024 KB)
pyl check --max-size 512

# Use a custom config file
pyl check --config /path/to/pyl.toml

# Write a GitHub Actions Job Summary
pyl check --github-summary

# List all built-in rules
pyl rules

# Generate a default config file
pyl init-config
```

### Exit codes

| Code | Meaning |
|------|---------|
| `0`  | No findings (or only LOW/WARNING severity) |
| `1`  | At least one CRITICAL, HIGH, or MEDIUM finding |

---

## Warnings

WARNING-level findings (e.g. plain HTTP URLs) are counted in the summary but suppressed in the detail output by default to reduce noise. Use `--warnings` to display them:

```bash
pyl check --warnings
```

The summary line always shows the WARNING count regardless of this flag.

---

## Configuration

Run `pyl init-config` to create a `pyl.toml` in the current directory:

```toml
[scan]
# Leave empty to scan all files (except .env and .git).
# Restrict to specific extensions:
# extensions = ["py", "js", "ts", "go", "yaml", "toml"]
extensions = []
exclude_paths = []
exclude_files = []

[rules]
# Disable specific rules by ID:
# disable = ["jwt-token", "http-insecure-url"]
disable = []
```

`pyl.toml` is auto-loaded from the current directory if present.

---

## Suppression

Add a suppression comment to any line to skip it:

```python
api_url = "http://internal-service/api"  # pyl-ignore
```

Supported markers: `# pyl-ignore`, `# noqa-secrets`, `# nosec-secrets`

pyl also automatically skips common false positives:

| Pattern | Example |
|---------|---------|
| Python f-strings / Jinja | `postgresql://{DB_USER}:{DB_PASSWORD}@...` |
| Shell variables | `$DB_PASSWORD` |
| Python `%`-format | `%(password)s` |
| Attribute references | `settings.DB_PASSWORD`, `config.secret_key` |
| localhost HTTP URLs | `http://localhost:8080` |

---

## Detection Coverage

| Category | Examples |
|----------|---------|
| **Cloud / VCS** | AWS keys, GitHub/GitLab PATs, Google API keys, Stripe, Slack, NPM, Docker Hub |
| **LLM / AI** | OpenAI, Anthropic, Cohere, Mistral, Hugging Face, Replicate, Groq, Perplexity |
| **Azure / M365** | Tenant/Client IDs, Storage keys, Service Bus, Cosmos DB, Teams webhooks, Graph API |
| **Frontend / SaaS** | Firebase, Mapbox, Sentry DSN, Contentful, Shopify, Algolia, Linear, Postman, PlanetScale, Cloudflare |
| **Databases** | PostgreSQL, MySQL, MongoDB, Redis, MSSQL, Elasticsearch, RabbitMQ, JDBC |
| **Observability** | Datadog, New Relic, Grafana, Honeycomb, Lightstep, OTLP endpoints |
| **HTTP Auth** | Basic Auth headers, Bearer tokens, credentials in URLs, curl commands |
| **Crypto** | PEM private keys (RSA, EC, DSA, OpenSSH) |
| **Generic** | High-entropy secrets matching common naming patterns, JWT tokens |

Run `pyl rules` to see all 89 rules with IDs, severity levels, and tags.

---

## Severity Levels

| Level | Description |
|-------|-------------|
| `CRITICAL` | Direct credential exposure — rotate immediately |
| `HIGH` | Sensitive token or key with significant access |
| `MEDIUM` | Potentially sensitive, context-dependent |
| `LOW` | Low-risk exposure (e.g. publishable keys) |
| `WARNING` | Best-practice violation (e.g. plain HTTP URLs) — shown with `--warnings` |

---

## GitHub Actions

### Use pyl in your own pipeline

Add this job to any workflow to scan for secrets and write the results to the GitHub Job Summary:

```yaml
jobs:
  pyl:
    name: pyl secret scan
    runs-on: ubuntu-latest
    permissions:
      contents: read

    steps:
      - uses: actions/checkout@v4

      - name: Install pyl
        run: |
          curl -sSfL \
            https://github.com/adrian-lorenz/pyl/releases/latest/download/pyl-linux-amd64 \
            -o /usr/local/bin/pyl
          chmod +x /usr/local/bin/pyl

      - name: Run scan
        run: pyl check --format markdown >> "$GITHUB_STEP_SUMMARY"
```

Or install via pip:

```yaml
      - name: Install pyl
        run: pip install pyl-secret-leaks

      - name: Run scan
        run: pyl check --format markdown >> "$GITHUB_STEP_SUMMARY"
```

---

Two ready-to-use workflows are also included in `.github/workflows/`.

### Secret scan on every push — `scan.yml`

Runs `pyl check` on every push and pull request, uploads results to GitHub Code Scanning as SARIF.

> Replace `YOUR_USERNAME` in `scan.yml` with your GitHub username before pushing.

### Release workflow — `release.yml`

Triggered automatically when you push a version tag:

```bash
git tag v1.0.0
git push origin v1.0.0
```

The workflow:
1. **Builds** Linux amd64/arm64 and Windows amd64/arm64 in parallel on `ubuntu-latest` using [`cross`](https://github.com/cross-rs/cross)
2. **Builds** macOS arm64 natively on `macos-latest`
3. **Creates** a GitHub Release with all 5 binaries attached and an auto-generated changelog

The release body includes a download table and install instructions automatically.

---

## Project Structure

```
src/
├── lib.rs        Library root, PyO3 Python bindings
├── main.rs       CLI entry point, CLI dispatch
├── cli.rs        CLI types (Cli, Commands, OutputFormat)
├── config.rs     Configuration loading (pyl.toml)
├── rules.rs      Built-in detection rules and Severity type
├── scanner.rs    File and directory scanning logic
└── output.rs     Output formatters (pretty, JSON, SARIF, GitHub Summary)
```

---

## License

MIT — Copyright (c) 2026 Adrian Lorenz &lt;a.lorenz@noa-x.de&gt;

