dependency-scout 0.1.0__tar.gz

dependency_scout-0.1.0/.claude/commands/add-check-plugin.md

@@ -0,0 +1,235 @@
+Create a standalone check plugin package for dependency-scout.
+
+Use this when you want to add a custom supply-chain check as a separate
+installable package — for example, an internal vulnerability database lookup,
+a proprietary license scanner, or a deep archive analysis that doesn't belong
+in the core.
+
+If the user provided arguments ($ARGUMENTS), treat them as a description of
+what the check will do. Otherwise ask: "What will this check do? (e.g.
+'look up packages in our internal vuln DB', 'scan archive contents for
+proprietary license markers', 'fetch SBOM from internal registry')"
+
+---
+
+## Step 1 — Choose the right tier
+
+Ask (or infer from context):
+
+**Tier A — Simple check** (`dependency_scout.checks`)
+- Plain `async def` — no Temporal knowledge required
+- Runs in parallel with all other checks; must finish in under ~30 seconds
+- Use this for: API lookups, database queries, lightweight analysis
+
+**Tier B — Advanced check** (`dependency_scout.activity_checks`)
+- Full Temporal `@activity.defn` — heartbeating, custom retry/timeout policies, cancellation
+- Requires per-repo opt-in in `.github/dependency-scout.yml`
+- Use this for: archive downloads, corpus scanning, anything that could take minutes or needs retry control
+
+When in doubt, suggest Tier A. Suggest Tier B only if the user mentions timeouts, heartbeating, long-running work, or archive/binary downloads.
+
+---
+
+## Step 2 — Scaffold the package
+
+Suggest a name like `dependency-scout-{org}-checks` or `dependency-scout-{topic}`.
+
+```
+my-plugin/
+├── pyproject.toml
+└── my_plugin/
+    ├── __init__.py        ← empty or minimal
+    └── checks.py          ← the check implementation
+```
+
+---
+
+## Step 3A — Tier A: Simple check
+
+### `my_plugin/checks.py`
+
+```python
+from models import CheckContext
+
+async def run(ctx: CheckContext) -> dict:
+    """
+    ctx fields: ctx.package, ctx.ecosystem, ctx.old_version, ctx.new_version
+    Return a dict — keys become fields in PackageChecks.custom_checks.
+    """
+    result = await my_internal_db.lookup(ctx.package, ctx.ecosystem)
+    return {
+        "internal_vuln_count": result.count,
+        "severity": result.max_severity,
+    }
+```
+
+Return a plain `dict`. Keys are arbitrary — choose names that will be
+meaningful in the LLM classifier prompt. Values must be JSON-serialisable.
+
+On failure, catch exceptions and return a degraded default rather than
+raising — the Scout treats any exception from a custom check as a
+non-fatal warning:
+
+```python
+async def run(ctx: CheckContext) -> dict:
+    try:
+        result = await my_internal_db.lookup(ctx.package, ctx.ecosystem)
+        return {"internal_vuln_count": result.count}
+    except Exception:
+        return {"internal_vuln_count": None}
+```
+
+### `pyproject.toml`
+
+```toml
+[project]
+name = "dependency-scout-my-checks"
+version = "0.1.0"
+dependencies = ["dependency-scout"]
+
+[project.entry-points."dependency_scout.checks"]
+my_check = "my_plugin.checks:run"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
+
+The entry-point name (`my_check` above) is the key your results are stored
+under in `PackageChecks.custom_checks`. Choose something unique and
+descriptive — it appears verbatim in the LLM classifier prompt.
+
+### How classifiers handle your results
+
+- **LLM classifiers (Claude, OpenAI, Ollama)** — your dict is injected
+  automatically into the prompt as labeled JSON in a `<untrusted_custom>`
+  block. No code changes needed.
+- **Rule-based classifier** — ignores `custom_checks` by design. If you need
+  rule-based support, contribute the check as a built-in (see contributing.md).
+
+No config changes are needed in target repos — plugins are discovered
+automatically from installed packages.
+
+---
+
+## Step 3B — Tier B: Advanced check
+
+### `my_plugin/checks.py`
+
+```python
+from temporalio import activity
+from models import CheckContext
+
+@activity.defn(name="my_company.deep_archive_scan")
+async def deep_archive_scan(ctx: CheckContext) -> dict:
+    # Call activity.heartbeat() periodically so Temporal knows you're alive.
+    # Without this, a stuck download silently times out.
+    activity.heartbeat()
+
+    # ... long-running analysis ...
+    data = await download_and_scan(ctx.package, ctx.new_version)
+
+    activity.heartbeat()  # call again after expensive steps
+    return {"suspicious_patterns": data.patterns, "risk_score": data.score}
+```
+
+The `name=` string in `@activity.defn` must be **globally unique** across all
+installed plugins. Use a namespaced format: `org.check_name`.
+
+### `pyproject.toml`
+
+```toml
+[project]
+name = "dependency-scout-my-checks"
+version = "0.1.0"
+dependencies = ["dependency-scout", "temporalio"]
+
+[project.entry-points."dependency_scout.activity_checks"]
+deep_scan = "my_plugin.checks:deep_archive_scan"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
+
+### Per-repo opt-in
+
+Unlike simple checks, activity checks require explicit opt-in in each repo's
+`.github/dependency-scout.yml`:
+
+```yaml
+extra_check_activities:
+  - my_company.deep_archive_scan   # must match the @activity.defn name exactly
+```
+
+The activity is registered with the worker at startup for all repos, but only
+called for repos that list it here.
+
+---
+
+## Step 4 — Install and verify
+
+```bash
+# Install your plugin into the Scout's environment
+uv pip install -e ../my-plugin
+
+# Verify the entry point is registered
+python -c "
+from importlib.metadata import entry_points
+# Change group to 'dependency_scout.activity_checks' for Tier B
+eps = entry_points(group='dependency_scout.checks')
+print([ep.name for ep in eps])
+"
+```
+
+For Tier A, run a quick triage to confirm your check fires and results appear:
+
+```bash
+uv run python triage.py --ecosystem pip --package requests --old 2.31.0 --new 2.32.0
+```
+
+Your check's results will appear in the verdict output under `custom_checks`.
+
+---
+
+## Step 5 — Test your check
+
+```python
+import pytest
+from temporalio.testing import ActivityEnvironment
+from models import CheckContext
+from my_plugin.checks import run  # or deep_archive_scan for Tier B
+
+@pytest.mark.asyncio
+async def test_my_check_success():
+    env = ActivityEnvironment()
+    ctx = CheckContext(
+        package="requests",
+        ecosystem="pip",
+        old_version="2.31.0",
+        new_version="2.32.0",
+    )
+    result = await env.run(run, ctx)
+    assert "internal_vuln_count" in result
+
+@pytest.mark.asyncio
+async def test_my_check_degrades_on_failure(monkeypatch):
+    # Simulate the external service being down
+    monkeypatch.setattr("my_plugin.checks.my_internal_db", broken_db)
+    env = ActivityEnvironment()
+    ctx = CheckContext(package="requests", ecosystem="pip",
+                       old_version="2.31.0", new_version="2.32.0")
+    result = await env.run(run, ctx)
+    assert result["internal_vuln_count"] is None  # degraded, not raised
+```
+
+---
+
+## Common pitfalls
+
+- **Tier B: plain async function silently skipped** — if you forget `@activity.defn`, the worker logs a WARNING and skips your check entirely. If your check isn't running, check the logs first.
+- **Tier B: `@activity.defn` name collision** — two plugins with the same `name=` string cause a registration error at worker startup. Always namespace: `my_company.check_name`.
+- **Tier B: no `extra_check_activities` in repo config** — the activity is registered but never called. This is intentional (opt-in), not a bug.
+- **Return non-serialisable types** — `datetime`, custom objects, etc. will cause serialisation errors. Stick to strings, numbers, lists, dicts, and `None`.
+- **Raising instead of degrading** — an unhandled exception in a simple check is caught by `run_all` and logged as a warning; the check result is omitted. In an activity check, Temporal will retry it according to the retry policy. Either way, prefer returning a degraded dict over raising.
+- **Entry point name conflicts** — two plugins with the same entry-point name (e.g. both registering `my_check`) will have one silently override the other. Use org-namespaced names.

dependency_scout-0.1.0/.claude/commands/add-detection.md

@@ -0,0 +1,93 @@
+Add a new supply chain attack detection pattern to the Scout.
+
+If the user provided arguments ($ARGUMENTS), treat them as a description of what to detect (attack name, behaviour, or package involved). Otherwise ask: "What attack or behaviour do you want to detect? (e.g. 'npm credential theft', 'Python .pth persistence', a CVE or blog post link)"
+
+Once you have a description, ask clarifying questions only if you cannot determine the answers from context:
+
+1. **Which kind of pattern is this?**
+   - Network call in library code (outbound HTTP) → `checks/signatures/net_calls.yaml`
+   - Obfuscated/encoded payload → `checks/signatures/obfuscation.yaml`
+   - OS persistence, self-propagation, credential theft → `checks/signatures/persistence.yaml`
+   - Suspicious file name or binary type → `checks/signatures/file_types.yaml`
+
+2. **Which language/extension?** (only for net_calls.yaml — it's keyed by file extension)
+
+---
+
+## Where to add it
+
+### New network call pattern — `checks/signatures/net_calls.yaml`
+
+Find the block for the file extension (`.py`, `.js`, `.ts`, `.rb`, etc.) and add:
+
+```yaml
+- pattern: 'YourRegexHere'
+  desc: what this detects and why it matters
+```
+
+Use **single-quoted** YAML strings for regex — single quotes never process backslash escapes, so `\b` and `\.` work as-is without doubling.
+
+If the extension doesn't exist yet, add a new block at the end:
+
+```yaml
+.ext:
+- pattern: 'SomeHTTPClient\b'
+  desc: HTTP client library for SomeLang
+```
+
+### OS persistence or worm propagation — `checks/signatures/persistence.yaml`
+
+Persistence goes under `patterns:`:
+
+```yaml
+- pattern: 'some\.persistence\.path'
+  desc: short-name (Attack/Repo/Date reference if known)
+```
+
+Worm propagation is a **compound rule** — the file must contain BOTH `credential_read` AND `publish_endpoint` to trigger. If the new attack has a two-step pattern, update both sub-keys under `worm_propagation:`.
+
+### Obfuscation — `checks/signatures/obfuscation.yaml`
+
+Keyed by extension, same format as net_calls.yaml.
+
+### Suspicious file names/types — `checks/signatures/file_types.yaml`
+
+Add to `suspicious_filenames:`, `suspicious_path_prefixes:`, `dangerous_binary_suffixes:`, or `install_hook_names:` as appropriate.
+
+---
+
+## Step — Add a test
+
+Open `tests/test_signatures.py` and add a test that checks your pattern actually matches a sample string, for example:
+
+```python
+def test_my_new_pattern_matches():
+    # .py network call
+    sample = "import my_new_http_lib"
+    assert any(p.search(sample) for p in NET_CALL_PATTERNS.get(".py", []))
+```
+
+Run:
+
+```bash
+uv run pytest tests/test_signatures.py -v
+```
+
+---
+
+## Step — Run the full suite
+
+```bash
+uv run ruff format checks/signatures/ tests/test_signatures.py
+uv run pytest -x -q
+```
+
+---
+
+## Common pitfalls
+
+- **Backslash doubling in YAML** — single-quoted strings (`'...'`) preserve regex backslashes literally. Double-quoted strings require `\\b`, `\\.`, etc. Always use single quotes.
+- **Single quotes inside single-quoted patterns** — `''` inside a single-quoted YAML string is an escaped `'`, but `'''` closes the string at the third quote and leaves the rest as bare YAML. If your regex needs to match a literal `'`, use `\S` or `[^\s]` instead, or rewrite to avoid quoting both `'` and `"` in the same character class.
+- **Too-broad patterns** — a pattern like `http` will match half the codebase. Prefer `\bhttplib2\b`, `requests\.get\b`, etc.
+- **Wrong file** — persistence patterns in net_calls.yaml (or vice versa) won't affect the right classifier signal.
+- **Compound worm rule** — the worm fires only when BOTH `credential_read` AND `publish_endpoint` appear in the **same file**. If you're describing a single-step attack, use a plain persistence pattern instead.

dependency_scout-0.1.0/.claude/commands/add-ecosystem.md

@@ -0,0 +1,108 @@
+Add a new package ecosystem provider to dependency-scout.
+
+If the user provided arguments ($ARGUMENTS), treat them as the ecosystem name or description. Otherwise ask: "What ecosystem are you adding? (e.g. 'PyPI', 'Hackage', 'Pub/Flutter')"
+
+Then collect any other details you need (registry URL, OSV ecosystem name, Dependabot slug) by looking at existing providers as reference, asking the user only for things you can't infer.
+
+---
+
+## What you're building
+
+A single file `ecosystems/{name}.py` that implements the `EcosystemProvider` protocol. The provider is auto-discovered at startup — no registry rows, no worker changes, no fixture regeneration needed.
+
+---
+
+## Step 1 — Create `ecosystems/{name}.py`
+
+Copy `ecosystems/cargo.py` as the closest structural template. The provider must have:
+
+**Four class attributes:**
+```python
+ecosystem_name  = "myeco"        # key used everywhere in the codebase
+osv_name        = "MyEco"        # must match api.osv.dev ecosystem name exactly
+dependabot_slug = "myeco"        # Dependabot's internal branch prefix (e.g. "npm_and_yarn",
+                                 # "pip", "cargo", "bundler", "maven", "nuget", "composer",
+                                 # "go_modules") — check github.com/dependabot/dependabot-core
+                                 # if unsure; used to parse Dependabot PR branch names
+name_re         = re.compile(r"^[a-z0-9_-]+$")  # package name allowlist for the webhook
+```
+
+**Seven async methods** (all must be present; return degraded defaults on failure, never raise):
+- `fetch_metadata(package, old_version, new_version) -> PyPIChecks` — download stats, description, major-bump flag
+- `fetch_release_age(package, new_version) -> ReleaseAgeChecks` — registry publish timestamp
+- `fetch_maintainer(package, old_version, new_version) -> MaintainerChecks` — who published each version
+- `get_archive_url(client, package, version) -> tuple[str, str, str] | None` — returns `(url, filename, integrity_hash)`; call `validate_archive_url(url)` before returning
+- `extract_archive(archive_bytes, filename, dest) -> None` — unpack the archive into `dest`
+- `fetch_attestations(package, old_version, new_version) -> AttestationChecks` — SLSA/Sigstore provenance; return `AttestationChecks(has_attestation=False)` if registry doesn't support it
+- `fetch_release(package, old_version, version) -> ReleaseChecks` — GitHub release checks; use the `fetch_vcs_release`, `fetch_vcs_tag_signature`, `fetch_vcs_ci_workflow_changes`, and `build_release_signals` helpers from `ecosystems/__init__.py` if the registry exposes a source repo URL
+
+Imports to start with:
+```python
+from models import (
+    AttestationChecks, MaintainerChecks, PyPIChecks,
+    ReleaseAgeChecks, ReleaseChecks,
+)
+from ecosystems import (
+    build_release_signals, fetch_vcs_release, fetch_vcs_tag_signature,
+    fetch_vcs_ci_workflow_changes, is_major, parse_upload_time,
+    parse_vcs_repo, validate_archive_url,
+)
+from helpers.http import get_client
+```
+
+## Step 2 — Add the CDN host
+
+Open `ecosystems/__init__.py` and add the registry's download CDN hostname to `ALLOWED_CDN_HOSTS`. This is enforced before any archive download — without it the diff check silently degrades.
+
+Example: if archives are served from `files.example-registry.org`, add that string to the frozenset.
+
+## Step 3 — Write tests
+
+Create `tests/test_{name}.py`. Use `tests/test_cargo.py` as the template — it covers all seven methods and is the cleanest example. Minimum required tests per method:
+
+- `fetch_metadata`: success case, 404/not-found case
+- `fetch_release_age`: success (recent release), success (old release), missing upload_time
+- `fetch_maintainer`: same publisher, changed publisher, API failure degrades gracefully
+- `get_archive_url`: returns valid tuple, CDN host is in ALLOWED_CDN_HOSTS
+- `extract_archive`: round-trips (create archive in test, extract, verify contents)
+- `fetch_attestations`: no-attestation case (if registry doesn't support it, just test it returns `has_attestation=False`)
+- `fetch_release`: no linked GitHub repo case, linked repo with release
+
+Mock HTTP with `respx`. Run activities inside `ActivityEnvironment()` from `temporalio.testing`.
+
+Keep coverage above 95% (`uv run pytest --cov=ecosystems --cov-report=term-missing`).
+
+## Step 4 — Run the full suite
+
+```bash
+uv run ruff format .
+uv run ruff check .
+uv run mypy .
+uv run pytest -x -q
+```
+
+The `test_check_wiring.py` tests will catch registration problems automatically. If they fail, check that `ecosystem_name` is set as a class attribute (not instance attribute) and that the file is directly inside `ecosystems/` (not a subdirectory).
+
+## Step 5 — Smoke test with a real package
+
+```bash
+uv run python -m start_workflow \
+  --ecosystem myeco \
+  --repo owner/some-repo \
+  --package some-package \
+  --old-version 1.0.0 \
+  --new-version 1.1.0 \
+  --pr-number 1
+```
+
+Watch the Temporal UI at http://localhost:8233 to confirm all activities complete (green checkmarks, not orange retries).
+
+---
+
+## Common pitfalls
+
+- **`dependabot_slug` wrong** — Dependabot PRs for your ecosystem won't be parsed. Check the Dependabot source or look at real PR branch names: `dependabot/{slug}/{package}-{version}`.
+- **`osv_name` wrong** — OSV vulnerability lookups return no results silently. Cross-check at https://api.osv.dev/v1/query with your ecosystem string.
+- **CDN host not in `ALLOWED_CDN_HOSTS`** — archive diff degrades to empty with no error logged at the activity level. Always add the host before testing.
+- **Raising from a method** — methods should catch their own exceptions and return degraded defaults. Only use `ApplicationError(..., non_retryable=True)` for permanent failures like 404 or auth errors.
+- **`parse_upload_time`** — use this helper for registry timestamps rather than `datetime.fromisoformat`; it handles the format variations across registries.

dependency_scout-0.1.0/.claude/commands/add-signature-plugin.md

@@ -0,0 +1,228 @@
+Create a standalone signature plugin package for dependency-scout.
+
+Use this when you want to ship attack signatures as a separate installable
+package rather than contributing them to the core `checks/signatures/` files —
+for example, org-internal threat intel, proprietary detection rules, or a
+community feed of patterns.
+
+If the user provided arguments ($ARGUMENTS), treat them as a description of
+what the plugin will detect. Otherwise ask: "What will this signature plugin
+detect? (e.g. 'internal threat intel feed', 'custom persistence patterns for
+our stack', 'patterns from a CVE feed')"
+
+---
+
+## Step 1 — Choose the right tier
+
+Ask (or infer from context):
+
+**Tier A — YAML directory** (`dependency_scout.signatures`)
+- Patterns are static and can be written as regex strings in YAML
+- No runtime dependencies or network calls needed
+- Lowest barrier: YAML files + a 3-line Python shim
+- Use this for: curated pattern lists, community rule sets, org-internal IOCs
+
+**Tier B — Python provider** (`dependency_scout.signature_providers`)
+- Patterns must be generated at runtime (fetched from an API, a database, generated programmatically)
+- Full Python — import anything, call anything
+- Use this for: threat-intel feeds, CVE APIs, patterns that change frequently
+
+When in doubt, suggest Tier A. If the user mentions "API", "feed", "dynamic", or "generated", suggest Tier B.
+
+---
+
+## Step 2 — Scaffold the package
+
+Create a directory for the plugin. If the user hasn't named it, suggest `dependency-scout-{org}-signatures` or `dependency-scout-{topic}-sigs`.
+
+```
+my-plugin/
+├── pyproject.toml
+└── my_plugin/
+    ├── __init__.py        ← empty or minimal
+    └── signatures.py      ← the entry point callable
+```
+
+For Tier A, also create:
+```
+    └── sigs/
+        ├── net_calls.yaml      ← optional: network call patterns
+        ├── persistence.yaml    ← optional: persistence/worm patterns
+        ├── obfuscation.yaml    ← optional: obfuscation patterns
+        └── file_types.yaml     ← optional: suspicious filenames/types
+```
+
+---
+
+## Step 3A — Tier A: YAML directory plugin
+
+### `my_plugin/signatures.py`
+
+```python
+from pathlib import Path
+
+def get_signatures_dir() -> Path:
+    return Path(__file__).parent / "sigs"
+```
+
+### YAML files (only create the ones you need)
+
+Use the same format as `checks/signatures/` in the core repo.
+
+**`sigs/net_calls.yaml`** — outbound network calls, keyed by file extension:
+```yaml
+.py:
+- pattern: 'evil_sdk\.fetch\b'
+  desc: EvilSDK HTTP client (SupplyChainCorp campaign May 2026)
+.js:
+- pattern: 'require\s*\(\s*[''"]evil-fetch[''"]\s*\)'
+  desc: evil-fetch npm package
+```
+
+**`sigs/persistence.yaml`** — OS persistence, self-propagation:
+```yaml
+patterns:
+- pattern: 'crontab.*attacker\.sh'
+  desc: cron-based persistence dropper
+```
+
+**`sigs/obfuscation.yaml`** — encoded payloads, keyed by extension:
+```yaml
+patterns:
+  .js:
+  - pattern: '_0xdeadbeef'
+    desc: javascript-obfuscator hex variable names
+```
+
+**`sigs/file_types.yaml`** — suspicious filenames and binary types:
+```yaml
+suspicious_filenames:
+  - evil.cfg
+suspicious_path_prefixes:
+  - .evil/
+dangerous_binary_suffixes:
+  - .evil
+install_hook_names:
+  - evil_install.sh
+npm_install_scripts:
+  - evil_install
+```
+
+**Single-quote pitfall:** `\b`, `\s`, `\.` all work as-is in single-quoted YAML strings. But `'''` inside a single-quoted string closes the string at the third quote — if your regex needs to match literal `'`, use `\S` or `[^\s]` instead, or rewrite to avoid `'` and `"` in the same character class.
+
+### `pyproject.toml`
+
+```toml
+[project]
+name = "dependency-scout-my-sigs"
+version = "0.1.0"
+dependencies = ["pyyaml>=6.0"]
+
+[project.entry-points."dependency_scout.signatures"]
+my_sigs = "my_plugin.signatures:get_signatures_dir"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
+
+---
+
+## Step 3B — Tier B: Python provider plugin
+
+### `my_plugin/signatures.py`
+
+```python
+from checks.signatures import SignatureContribution
+
+def get_signatures() -> SignatureContribution:
+    # Fetch from API, database, or generate programmatically
+    patterns = _fetch_from_threat_feed()
+    return SignatureContribution(
+        net_call_patterns={".py": patterns["python_net_calls"]},
+        persistence_patterns=patterns["persistence"],
+    )
+```
+
+Only populate the fields you are contributing — omitted fields are ignored.
+All pattern strings are raw regex strings; they are compiled internally.
+
+`SignatureContribution` fields:
+| Field | Type | What it adds to |
+|---|---|---|
+| `net_call_patterns` | `dict[str, list[str]]` | `NET_CALL_PATTERNS` (keyed by extension) |
+| `obfuscation_patterns` | `dict[str, list[str]]` | `OBFUSCATION_PATTERNS` (keyed by extension) |
+| `persistence_patterns` | `list[str]` | `PERSISTENCE_PATTERNS` |
+| `suspicious_package_files` | `list[str]` | `SUSPICIOUS_PACKAGE_FILES` |
+| `suspicious_package_prefixes` | `list[str]` | `SUSPICIOUS_PACKAGE_PREFIXES` |
+| `dangerous_binary_suffixes` | `list[str]` | `DANGEROUS_BINARY_SUFFIXES` |
+| `install_hook_names` | `list[str]` | `INSTALL_HOOK_NAMES` |
+| `npm_install_scripts` | `list[str]` | `NPM_INSTALL_SCRIPTS` |
+
+### `pyproject.toml`
+
+```toml
+[project]
+name = "dependency-scout-my-provider"
+version = "0.1.0"
+dependencies = ["dependency-scout"]  # for SignatureContribution
+
+[project.entry-points."dependency_scout.signature_providers"]
+my_provider = "my_plugin.signatures:get_signatures"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
+
+---
+
+## Step 4 — Install and verify
+
+```bash
+# From the core repo, install your plugin in editable mode
+uv pip install -e ../my-plugin
+
+# Verify the entry point is discovered
+python -c "
+from importlib.metadata import entry_points
+eps = entry_points(group='dependency_scout.signatures')  # or signature_providers
+print([ep.name for ep in eps])
+"
+
+# Verify patterns are merged into the constants
+python -c "
+from checks.signatures import NET_CALL_PATTERNS, PERSISTENCE_PATTERNS
+print('Extensions covered:', list(NET_CALL_PATTERNS.keys()))
+print('Persistence pattern count:', len(PERSISTENCE_PATTERNS))
+"
+```
+
+---
+
+## Step 5 — Test your patterns
+
+Write a test that directly imports from `checks.signatures` after installing your plugin and checks that your patterns are present:
+
+```python
+from checks.signatures import NET_CALL_PATTERNS, PERSISTENCE_PATTERNS
+
+def test_my_pattern_is_loaded():
+    patterns = NET_CALL_PATTERNS.get(".py", [])
+    assert any(p.search("evil_sdk.fetch(url)") for p in patterns)
+```
+
+Run the core test suite to confirm nothing regresses:
+```bash
+uv run pytest -x -q
+```
+
+---
+
+## Common pitfalls
+
+- **Entry point not discovered** — run `uv pip install -e .` in your plugin directory; entry points only register on install.
+- **`dependency_scout.signatures` vs `dependency_scout.signature_providers`** — wrong group means silent no-op; the discovery loop skips unrecognised groups entirely.
+- **Tier B: exceptions crash silently** — broken providers are caught and logged as WARNING, not raised. If your patterns aren't showing up, check the logs at WARNING level.
+- **Tier A: missing YAML files are skipped** — you don't need all four YAML files; only the ones present in your `sigs/` directory are merged. But a present file that fails to parse is also silently skipped (with a WARNING).
+- **Pattern too broad** — test with real package diffs, not just unit tests. A pattern like `fetch` will fire on half the internet.

dependency_scout-0.1.0/.claude/commands/triage-test.md

@@ -0,0 +1,20 @@
+Run a one-off triage against a real package to test the Scout locally.
+
+Parse $ARGUMENTS for ecosystem, package, old version, and new version. If any are missing, ask the user. Repo and PR number can be anything (they only affect whether real PR actions fire, which is off by default).
+
+Then run:
+
+```bash
+uv run python -m start_workflow \
+  --repo owner/test-repo \
+  --package {package} \
+  --old-version {old} \
+  --new-version {new} \
+  --pr-number 1
+```
+
+If the user specified an ecosystem other than pip, add `--ecosystem {ecosystem}`.
+
+Remind them to open http://localhost:8233 to watch the workflow run in the Temporal UI, and that Temporal must be running (`temporal server start-dev` in a separate terminal) for this to work.
+
+After the command returns, show the verdict that was printed to stdout.