zwischen 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: beb48773e7ec58217010758614752399220a826e232e7af0c4b46a0ae603e304
+  data.tar.gz: 4bd6a34f9299e1e623843476523e13bd736c5c2c21c19b6e37029d9a63af2810
+SHA512:
+  metadata.gz: 72d2fda3d959f4b2621e8011fb03359e70b08db713665f30bff2129a98b2c09f19d2243a191d2a07739dec397570eb13a1c924e9a2f4d4ff71331c94ede9df0a
+  data.tar.gz: 624e96024130b6ab369f2d137d294941808d98c331a6ec1f2ecb1830cdbd5a30750be67a5840d179fd05f7c8ca3b2196c2643a2e32aff2baea025fae2d5e47a7

data/.zwischen.yml.example

@@ -0,0 +1,49 @@
+# Zwischen Configuration
+# Copy this file to .zwischen.yml in your project root
+
+# AI Provider Configuration
+ai:
+  enabled: true            # Enable AI for manual 'zwischen scan'
+  pre_push_enabled: false  # Disable AI in pre-push hooks (performance)
+  provider: claude         # Options: claude, ollama, openai
+  
+  # Provider-specific settings
+  ollama:
+    model: llama3
+    url: http://localhost:11434
+  
+  openai:
+    model: gpt-4
+  
+  claude:
+    model: claude-3-5-sonnet-20241022
+
+  # api_key: null   # Leave null to use ~/.zwischen/credentials or env vars (ANTHROPIC_API_KEY, OPENAI_API_KEY)
+
+# What blocks a push
+blocking:
+  severity: high  # block on high or critical (default)
+  # severity: critical  # only block on critical
+  # severity: none  # never block, just warn
+
+# Scanner Configuration
+scanners:
+  gitleaks: true  # Auto-installed to ~/.zwischen/bin/ if missing
+  semgrep: true   # Optional, install with: pip install semgrep
+  # Or use detailed format:
+  # gitleaks:
+  #   enabled: true
+  # semgrep:
+  #   enabled: true
+  #   config: p/security-audit  # Open ruleset, no login required
+  #   # Other options: p/secrets, p/owasp-top-ten, or path to custom ruleset
+
+# Ignored Paths — findings in matching paths are dropped before reporting.
+
+ignore:
+  - "**/vendor/**"
+  - "**/node_modules/**"
+  - "**/.git/**"
+  - "**/dist/**"
+  - "**/build/**"
+  - "**/test/fixtures/**"

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-10
+
+### Added
+- Initial release
+- Gitleaks and Semgrep scanner orchestration with auto-install
+- AI-powered finding triage via Ollama, OpenAI, or Anthropic
+- Pre-push git hook that blocks pushes introducing secrets or security issues
+- Project type detection (Next.js, React, Django, Rails, and more)
+- npm (`zwischen`) and pip (`zwischen-cli`) wrapper packages
+
+[Unreleased]: https://github.com/cjordan223/zwischen/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/cjordan223/zwischen/releases/tag/v0.1.0

data/DEVELOPMENT.md

@@ -0,0 +1,154 @@
+# Development Guide
+
+This repository contains three installable surfaces for the same product idea:
+
+- `lib/zwischen`: the Ruby gem and canonical implementation.
+- `packages/npm`: a Node.js wrapper package.
+- `packages/pip`: a Python wrapper package.
+
+When behavior differs, treat the Ruby gem as the source of truth unless the change is explicitly package-wrapper work.
+
+## Ruby Command Flow
+
+```text
+bin/zwischen
+  -> Zwischen::CLI
+     -> Config.load
+     -> ProjectDetector.detect
+     -> Scanner::Orchestrator
+        -> Scanner::Gitleaks
+        -> Scanner::Semgrep
+     -> Finding::Aggregator
+     -> AI::Analyzer, when enabled
+     -> Reporter::Terminal
+```
+
+`zwischen init` follows a separate path:
+
+```text
+CLI#init
+  -> Setup.run
+     -> Installer checks/installs Gitleaks
+     -> Credentials saves ANTHROPIC_API_KEY when present
+     -> Hooks installs .git/hooks/pre-push
+     -> Config.init creates .zwischen.yml
+```
+
+`zwischen scan --pre-push` uses `GitDiff.changed_files`, passes those files to scanner adapters, filters findings to changed files again as a safety net, and only prints compact output for blocking findings.
+
+## Config Contract
+
+Project config lives at `.zwischen.yml`.
+
+Current Ruby defaults:
+
+- `ai.enabled: true`
+- `ai.pre_push_enabled: false`
+- `ai.provider: claude`
+- `blocking.severity: high`
+- Gitleaks and Semgrep enabled
+- Semgrep config: `p/security-audit`
+
+Credential lookup order is environment variables first, then `~/.zwischen/credentials`.
+
+Supported Ruby credential environment variables:
+
+- `ANTHROPIC_API_KEY` for `claude`
+- `OPENAI_API_KEY` for `openai`
+
+Local tool installs use `~/.zwischen/bin`.
+
+## Common Change Checklists
+
+Scanner changes:
+
+- Add or edit a scanner under `lib/zwischen/scanner`.
+- Return `Zwischen::Finding::Finding` objects with normalized `type`, `scanner`, `severity`, `file`, `line`, `message`, and `rule_id`.
+- Register new scanner selection in `Scanner::Orchestrator`.
+- Update `.zwischen.yml.example`, `README.md`, and relevant specs.
+- Add or update scanner specs.
+
+AI provider changes:
+
+- Add a client under `lib/zwischen/ai`.
+- Wire provider selection in `AI::Analyzer`.
+- Add credential mapping in `Credentials` if the provider needs an API key.
+- Update `.zwischen.yml.example`, `README.md`, and AI specs.
+
+Hook changes:
+
+- Update `Hooks` and `Setup`.
+- Run installed-gem tests from `TESTING.md`.
+- Update `TESTING.md` with exact hook behavior and bypass behavior.
+
+Package-wrapper parity changes:
+
+- Mirror command flags in `packages/npm/bin/zwischen.js` and `packages/pip/zwischen/cli.py`.
+- Keep config key names aligned with `.zwischen.yml.example`.
+- Update wrapper package READMEs.
+
+## Known Iteration Points
+
+- Ruby `Hooks.handle_existing_hook` has backup/append/skip logic, but `Setup#install_hook` currently backs up and replaces existing non-Zwischen hooks directly.
+- Ruby config exposes `ignore` and `severity.fail_on`, but scanner adapters currently do not enforce ignore globs and blocking uses `blocking.severity`.
+- npm and pip wrappers do not yet match Ruby feature parity. They do not support `uninstall`, `--only`, Ruby's changed-file pre-push filtering, or the Ruby JSON summary shape.
+- npm and pip wrappers default AI provider to Ollama, while Ruby defaults to Claude.
+
+## Verification
+
+Ruby unit suite:
+
+```bash
+bundle exec rspec
+```
+
+Installed-gem workflow:
+
+```bash
+./scripts/test_as_gem.sh
+```
+
+Then follow `TESTING.md` from a temporary directory outside this repository.
+
+npm wrapper smoke checks:
+
+```bash
+cd packages/npm
+npm test
+node bin/zwischen.js --help
+```
+
+pip wrapper smoke checks:
+
+```bash
+cd packages/pip
+python -m pip install -e .
+zwischen --help
+```
+
+## Releasing
+
+Releases are automated by `.github/workflows/release.yml`, triggered by a
+version tag:
+
+```bash
+# bump lib/zwischen/version.rb, packages/npm/package.json,
+# packages/pip/pyproject.toml, and CHANGELOG.md first
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+One-time registry setup (first release only):
+
+1. **RubyGems** — add a *pending trusted publisher* for the `zwischen` gem at
+   <https://rubygems.org/profile/oidc/pending_trusted_publishers>:
+   repository `cjordan223/zwischen`, workflow `release.yml`, environment `release`.
+2. **PyPI** — add a *pending trusted publisher* for the `zwischen-cli` project at
+   <https://pypi.org/manage/account/publishing/> with the same repository,
+   workflow, and environment. (The bare `zwischen` name is taken on PyPI by an
+   unrelated package, so the distribution is `zwischen-cli`; the installed
+   command is still `zwischen`.)
+3. **npm** — create an automation token at npmjs.com and save it as the
+   `NPM_TOKEN` repository secret.
+4. **GitHub** — create a `release` environment in the repo settings
+   (Settings → Environments) so the OIDC claims match.

data/README.md

@@ -0,0 +1,207 @@
+# Zwischen
+
+[![CI](https://github.com/cjordan223/zwischen/actions/workflows/ci.yml/badge.svg)](https://github.com/cjordan223/zwischen/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/zwischen)](https://rubygems.org/gems/zwischen)
+[![npm](https://img.shields.io/npm/v/zwischen)](https://www.npmjs.com/package/zwischen)
+[![PyPI](https://img.shields.io/pypi/v/zwischen-cli)](https://pypi.org/project/zwischen-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+![Zwischen blocking a push that contains an AWS secret](docs/demo.gif)
+
+**Zwischen blocks `git push` the moment you're about to leak a secret** — the
+last point where a leaked credential is still a local problem instead of an
+incident. It orchestrates [Gitleaks](https://github.com/gitleaks/gitleaks)
+and [Semgrep](https://semgrep.dev), normalizes their findings, and (optionally)
+asks an AI provider — including fully local models via Ollama — to prioritize
+the results, flag false positives, and suggest fixes.
+
+One command sets everything up:
+
+```bash
+zwischen init   # installs gitleaks if missing, creates config, installs the pre-push hook
+```
+
+## Try it on a deliberately vulnerable app
+
+The [zwischen-demo](https://github.com/cjordan223/zwischen-demo) repository
+is a small Express app seeded with fake secrets and real vulnerability
+patterns. Clone it and watch a push get blocked in under a minute.
+
+## Installation
+
+```bash
+gem install zwischen        # canonical implementation (Ruby)
+npm install -g zwischen     # Node wrapper
+pip install zwischen-cli    # Python wrapper (command is still `zwischen`)
+```
+
+For local development from this repository:
+
+```bash
+bundle install
+bundle exec ruby -Ilib bin/zwischen --help
+```
+
+## Quick start
+
+Run these from the project you want to protect:
+
+```bash
+zwischen init     # config + pre-push hook + gitleaks auto-install
+zwischen scan     # manual scan with full report
+zwischen doctor   # check tool status
+```
+
+## AI triage
+
+Raw scanner output tells you *what matched*. The AI pass tells you *what to
+fix first and how* — see the real before/after in
+[docs/triage-example.md](docs/triage-example.md), generated with a local
+model via Ollama.
+
+| Provider | Flag | Setup |
+| --- | --- | --- |
+| Claude | `--ai claude` | Set `ANTHROPIC_API_KEY` or pass `--api-key`. |
+| Ollama | `--ai ollama` | Install Ollama and pull a model. Local-first: nothing leaves your machine. |
+| OpenAI | `--ai openai` | Set `OPENAI_API_KEY` or pass `--api-key`. |
+
+Manual scans use AI when `--ai` is passed or config enables it. Pre-push
+scans stay scanner-only unless `ai.pre_push_enabled: true` — blocking
+decisions should be fast and deterministic. The design rationale is in
+[docs/design.md](docs/design.md).
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `zwischen init` | Installs/checks tools, creates config, installs pre-push hook (backs up an existing non-Zwischen hook). |
+| `zwischen scan` | Runs enabled scanners, prints a terminal report. |
+| `zwischen scan --changed` | Scans only files changed since the default branch. |
+| `zwischen scan --only secrets,sast` | Limits to Gitleaks (`secrets`) and/or Semgrep (`sast`). |
+| `zwischen scan --ai <provider>` | Adds AI prioritization, fix suggestions, false-positive detection. |
+| `zwischen scan --format json` | Machine-readable summary + findings. |
+| `zwischen scan --format sarif` | SARIF 2.1.0 for GitHub code scanning. |
+| `zwischen scan --pre-push` | Quiet hook mode: changed files only, compact output only when blocking. |
+| `zwischen doctor` | Shows Gitleaks and Semgrep status. |
+| `zwischen uninstall` | Removes the hook, optionally config/credentials. |
+
+Escape hatches: `git push --no-verify` or `ZWISCHEN_SKIP=1 git push`.
+
+## GitHub Action
+
+Run the same scan in CI and feed the GitHub Security tab:
+
+```yaml
+- uses: cjordan223/zwischen@main
+  with:
+    sarif-file: zwischen.sarif
+- uses: github/codeql-action/upload-sarif@v3
+  if: always()
+  with:
+    sarif_file: zwischen.sarif
+```
+
+## Configuration
+
+Create or edit `.zwischen.yml` in the scanned project:
+
+```yaml
+ai:
+  enabled: true
+  pre_push_enabled: false
+  provider: claude          # claude, ollama, or openai
+  ollama:
+    model: llama3
+    url: http://localhost:11434
+    timeout: 180            # seconds; local models can be slow to load
+
+blocking:
+  severity: high            # high, critical, or none
+
+scanners:
+  gitleaks:
+    enabled: true
+  semgrep:
+    enabled: true
+    config: p/security-audit,p/expressjs   # comma-separated rulesets
+
+ignore:                     # findings under these globs are dropped
+  - "**/node_modules/**"
+  - "**/test/fixtures/**"
+```
+
+Boolean scanner entries (`gitleaks: true`) work too. Credentials are read
+from environment variables first, then `~/.zwischen/credentials` (written by
+`zwischen init` when `ANTHROPIC_API_KEY` is set).
+
+## Architecture
+
+```mermaid
+flowchart LR
+    push[git push] --> hook[pre-push hook]
+    hook --> diff[GitDiff<br/>changed files]
+    diff --> orch[Orchestrator]
+    cli[zwischen scan] --> orch
+    orch --> gl[Gitleaks<br/>secrets]
+    orch --> sg[Semgrep<br/>SAST]
+    gl --> agg[Aggregator<br/>normalize + dedupe<br/>+ ignore globs]
+    sg --> agg
+    agg --> ai{AI enabled?}
+    ai -- yes --> llm[Claude / OpenAI / Ollama<br/>priority · fixes · false positives]
+    ai -- no --> rep
+    llm --> rep[Reporter]
+    rep --> term[terminal / compact]
+    rep --> mach[json / sarif]
+    term --> block{blocking<br/>finding?}
+    block -- yes --> deny[⛔ push blocked]
+    block -- no --> allow[✓ push proceeds]
+```
+
+The Ruby gem is the canonical implementation; the npm and pip packages are
+convenience wrappers with a smaller command surface.
+
+## Wrapper parity
+
+| Capability | Ruby gem | npm / pip wrappers |
+| --- | --- | --- |
+| `init` / `scan` / `doctor` | ✓ | ✓ |
+| `uninstall` | ✓ | — |
+| `--only` scanner selection | ✓ | — |
+| `--changed` / changed-file pre-push filtering | ✓ | — (hook scans the project) |
+| `--format json` | ✓ | ✓ |
+| `--format sarif` | ✓ | — |
+| AI providers | claude, ollama, openai | ollama, openai, anthropic |
+
+The wrapper gaps are intentional scope decisions, not bugs: the wrappers
+exist so `npm install -g zwischen` / `pip install zwischen-cli` work in
+ecosystems where a Ruby gem is friction, and they track the core workflow
+(init → hook → scan) rather than every flag.
+
+## Repository layout
+
+```text
+bin/zwischen                  Ruby executable
+lib/zwischen/                 Ruby gem implementation
+lib/zwischen/scanner/         Gitleaks and Semgrep adapters
+lib/zwischen/ai/              Claude, Ollama, and OpenAI clients
+lib/zwischen/reporter/        Terminal and SARIF reporters
+packages/npm/                 Node wrapper package
+packages/pip/                 Python wrapper package
+spec/                         RSpec suite
+action.yml                    Composite GitHub Action
+docs/                         Design write-up, triage example, demo GIF
+```
+
+## Development
+
+```bash
+bundle exec rspec             # 196+ examples
+./scripts/test_as_gem.sh      # install and exercise as a real gem
+```
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for architecture notes and the release
+process, and [TESTING.md](TESTING.md) for the end-to-end test plan.
+
+## License
+
+MIT