langdoctor 0.1.0__tar.gz

langdoctor-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff check .
+
+  test:
+    name: py${{ matrix.python-version }} · ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e ".[dev]"
+      - run: pytest -q

langdoctor-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,80 @@
+name: Release
+
+# Publishing uses PyPI Trusted Publishing (OIDC) — no API token is stored.
+# The trusted publisher is configured for: repo elaz48/langdoctor,
+# workflow release.yml, environment pypi. Those three MUST NOT change or
+# publishing will fail.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: py${{ matrix.python-version }} · ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e ".[dev]"
+      - run: pytest -q
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # OIDC token for PyPI Trusted Publishing
+      contents: write   # create the GitHub Release
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Guard — tag must equal package __version__
+        run: |
+          set -euo pipefail
+          TAG="${GITHUB_REF_NAME#v}"
+          VERSION="$(python -c "import re,pathlib; \
+            t=pathlib.Path('src/langdoctor/__init__.py').read_text(); \
+            print(re.search(r'__version__ = \"([^\"]+)\"', t).group(1))")"
+          echo "tag=$TAG  package_version=$VERSION"
+          if [ "$TAG" != "$VERSION" ]; then
+            echo "::error::git tag v$TAG does not match package __version__ $VERSION"
+            exit 1
+          fi
+
+      - name: Build with uv
+        run: |
+          python -m pip install uv
+          uv build
+
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1  # langdoctor: ignore=LD502  (PyPA publisher; pin to a SHA for max hardening)
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          VER="${GITHUB_REF_NAME#v}"
+          NOTES="$(awk -v ver="$VER" '
+            /^## \[/ { if (seen) exit; if (index($0, "[" ver "]")) { seen=1; next } }
+            seen
+          ' CHANGELOG.md)"
+          [ -z "$NOTES" ] && NOTES="See CHANGELOG.md."
+          gh release create "${GITHUB_REF_NAME}" dist/* \
+            --title "${GITHUB_REF_NAME}" \
+            --notes "$NOTES"

langdoctor-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# ECC / Claude Code project harness (local-only)
+.claude/
+
+# Python
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/

langdoctor-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,7 @@
+- id: langdoctor
+  name: langdoctor
+  description: "Scan the project for known LangGraph/LangChain CVEs, insecure configs, and production footguns."
+  entry: langdoctor
+  language: python
+  pass_filenames: false
+  always_run: true

langdoctor-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to langdoctor are documented here.
+The format follows [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-07-04
+
+Initial release.
+
+### Added
+- **Known-CVE checks (data-driven, offline).** 12 advisories for
+  LangGraph / LangChain / Langflow (LD101–LD111 + the LD150 Langflow catch-all),
+  shipped in `advisories.json` (schema v2): OSV-style `affected_ranges`
+  (including dual-line fixes), CVSS-derived severity with a manual override,
+  `exploited_in_the_wild` (KEV) flags, and `aliases`.
+- **Code-pattern checks.** Checkpointer/state (LD201–204), graph/runtime config
+  (LD301–304), secrets & exposure (LD401–403, LD203), and hygiene (LD501–502) —
+  via cached stdlib-`ast` analysis and file heuristics.
+- **Project scanner** for `requirements.txt`, `pyproject.toml` (PEP 621 +
+  poetry), `uv.lock`, and `poetry.lock`, plus Python-source discovery.
+- **CLI**: `langdoctor [PATH]`, `list-checks`, `--version`; `--fail-on`,
+  `--strict`, `--ignore`, `--quiet`; exit codes 0 (clean) / 1 (findings) / 2
+  (scan error).
+- **Output formats**: console, json, sarif (2.1.0 for GitHub code scanning, with
+  CVSS-backed `security-severity`), and markdown.
+- **Config & suppression**: `[tool.langdoctor]` (`fail-on`/`ignore`/`exclude`)
+  and inline `# langdoctor: ignore[=IDs]` matched on LD id / CVE / alias
+  (case-insensitive). Suppressed findings are counted, never hidden.
+- **Integrations**: composite GitHub Action (`action.yml`, install pinned to the
+  action's own ref) and `.pre-commit-hooks.yaml`.
+
+### Fixed
+- Scanner `DEFAULT_EXCLUDES` matched any path component, silently excluding a
+  top-level `.env` file and breaking LD402/LD403 detection.
+
+[Unreleased]: https://github.com/elaz48/langdoctor/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/elaz48/langdoctor/releases/tag/v0.1.0

langdoctor-0.1.0/CLAUDE.md

@@ -0,0 +1,109 @@
+# CLAUDE.md
+
+Guidance for Claude Code working in this repository. The authoritative brief is
+`langdoctor-spec.md`; this file distills the parts that must stay consistent
+across sessions.
+
+## Project
+
+**langdoctor** — a production-readiness and security audit CLI for
+LangGraph / LangChain / Langflow projects. "brew doctor for your agent stack."
+Scans a project for known CVEs, insecure configs, and production footguns —
+in seconds, offline, no API key. MIT licensed (© 2026 elaz48).
+
+## Design principles (non-negotiable)
+
+1. **Deterministic.** No AI/LLM API calls. Same input → same output, always.
+2. **Offline-first.** Zero network calls during a scan. CVE data ships in the
+   package (`src/langdoctor/data/advisories.json`).
+3. **Zero-config.** `pipx run langdoctor` / `uvx langdoctor` in a project dir must
+   produce useful output with no setup.
+4. **CI-native.** Meaningful exit codes, JSON/SARIF/markdown output, quiet mode.
+5. **Fast.** Full scan of a typical project under ~2s.
+
+Non-goals (v1): runtime monitoring, prompt-injection detection, LLM-based
+analysis, frameworks other than LangChain/LangGraph/Langflow.
+
+## Architecture map
+
+`scanner` (discover project files) → `engine` (run registered checks) →
+`Finding`s → `output/` (console | json | sarif | markdown). Full tree in spec §3.
+
+- **Checks are data-driven where possible.** Version/CVE checks read
+  `advisories.json`; code-pattern checks are Python functions registered via
+  `@register_check(...)`.
+- Keep dependencies minimal and pure-Python: `rich`, `packaging`,
+  `tomli` (only < 3.11; use stdlib `tomllib` on 3.11+), stdlib `ast`.
+
+## Advisories are DATA, not code
+
+Adding a new CVE = edit `advisories.json` + add one vulnerable/clean fixture
+pair + ship a **patch** release. Never hardcode a CVE threshold in Python. The
+advisory DB is the product's live surface and its marketing engine (spec §9).
+
+`advisories.json` is **schema_version 2** (spec §5). Key rules:
+- Version applicability via `affected_ranges` (OSV-style `{introduced, fixed}`
+  list, compared with `packaging.version`). `fixed_in` is a human summary ONLY —
+  never the comparison source of truth. This models dual-line fixes (e.g. LD105
+  patched on both 0.3.x and 1.x).
+- **Severity is derived from `cvss_score`** via `severity_buckets`
+  (≥9.0 critical / ≥7.0 high / ≥4.0 medium / ≥0.1 low). `severity_override`
+  wins when set (CNA-vs-NVD disagreements happen — see LD105).
+- `exploited_in_the_wild` (KEV) bumps display priority above all non-KEV
+  findings regardless of CVSS, with a 🔴 KEV badge.
+- `aliases` (GHSA/PYSEC/duplicate CVE IDs): lookup, `--ignore`, and inline
+  `# langdoctor: ignore=` suppression must match the LD id, primary CVE, OR any
+  alias. The engine must tolerate unknown fields (forward compatibility).
+
+## Check-ID conventions
+
+Every advisory/check has a stable ID `LD###`, categorized by hundreds:
+- `1xx` known vulnerabilities (data-driven), `2xx` checkpointer & state,
+  `3xx` graph & runtime config, `4xx` secrets & exposure, `5xx` hygiene.
+- IDs are permanent identifiers — never renumber a shipped ID; deprecate instead.
+- Users suppress by ID; docs deep-link by ID.
+
+## False-positive policy
+
+Heuristic checks (e.g. LD203, LD302) MUST print "heuristic" in output and MUST
+NOT affect CI exit code by default — only under `--strict`. Trust is the product.
+
+## Verification discipline (learned in Phase 0)
+
+**OSV.dev lags NVD and vendor advisories.** CVE-2026-5027 (LD111) was real and
+actively exploited but absent from OSV at build time. When adding/verifying an
+advisory: cross-check ≥2 sources (OSV + NVD + GitHub Security Advisories /
+vendor), record every identifier in `aliases`, and pull CVSS base scores from
+NVD (do not hand-compute). Numbers are "verified-as-of a date," never permanent.
+
+## Commands
+
+Python 3.10+ (ecosystem floor, verified). Cross-platform: `pathlib` everywhere,
+no shelling out, explicit UTF-8 (`encoding="utf-8", errors="replace"`), respect
+`NO_COLOR` and non-TTY.
+
+| Task | Command |
+|------|---------|
+| Run | `python -m langdoctor [PATH]` (editable: `pip install -e .`) |
+| Test | `pytest` (target suite < 30s) |
+| Lint | `ruff check .` / `ruff format .` |
+| Build | `uv build` |
+
+## Release / deployment constraints (IMPORTANT)
+
+- **PyPI Trusted Publishing (OIDC, no stored token).** The release workflow MUST
+  match the pre-configured Trusted Publisher exactly or publishing fails:
+  owner `elaz48`, repo `langdoctor`, workflow filename `release.yml`,
+  environment `pypi`. Release trigger: push tag `vX.Y.Z` → full test matrix →
+  `uv build` → publish → GitHub Release with changelog.
+- **CI matrix:** ubuntu / macos / windows × Python 3.10 / 3.12 / 3.13; ruff + pytest.
+- **Website (`langdoctor.dev`)** is a single self-contained static HTML file
+  (spec §10), uploaded **manually via FTP to PHP/DirectAdmin shared hosting**.
+  Do NOT set up GitHub Pages or any Actions-based site deploy.
+
+## Working agreement
+
+Build phase-by-phase per spec §11 (skeleton → full catalog → output/integration
+→ polish/release → website). Pause for review at the end of each phase. Follow
+the spec's architecture, check catalog, and CLI exactly unless there's a
+concrete technical reason to deviate — then flag it, don't silently change course.

langdoctor-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 elaz48
+
+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.

langdoctor-0.1.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: langdoctor
+Version: 0.1.0
+Summary: Production-readiness and security audit CLI for LangGraph / LangChain projects — brew doctor for your agent stack.
+Project-URL: Homepage, https://langdoctor.dev
+Project-URL: Repository, https://github.com/elaz48/langdoctor
+Project-URL: Issues, https://github.com/elaz48/langdoctor/issues
+Author: Balazs Hende
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,cli,devsecops,langchain,langflow,langgraph,llm-security,sast,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: packaging>=23.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# langdoctor 🩺
+
+> **Scan your LangGraph/LangChain project for known CVEs, insecure configs, and production footguns — in seconds, offline, no API key.**
+>
+> _brew doctor for your agent stack._
+
+[![PyPI](https://img.shields.io/pypi/v/langdoctor.svg)](https://pypi.org/project/langdoctor/)
+[![Python](https://img.shields.io/pypi/pyversions/langdoctor.svg)](https://pypi.org/project/langdoctor/)
+[![CI](https://github.com/elaz48/langdoctor/actions/workflows/ci.yml/badge.svg)](https://github.com/elaz48/langdoctor/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+![langdoctor scanning a vulnerable project](https://raw.githubusercontent.com/elaz48/langdoctor/main/assets/demo.gif)
+
+## Quickstart
+
+```bash
+pipx run langdoctor        # or: uvx langdoctor
+```
+
+Run it in your project directory. langdoctor reads your dependency files and
+source, reports issues grouped by severity, and exits non-zero when it finds
+something at or above your threshold.
+
+```bash
+langdoctor                 # scan the current directory
+langdoctor path/to/project # scan a specific directory
+langdoctor list-checks     # every check, with IDs and severities
+langdoctor --version       # tool version + advisory DB date
+```
+
+## Why
+
+2026 has been a rough year for the agent stack:
+
+- **Langflow is under active attack.** `CVE-2025-3248` (unauthenticated RCE) was
+  added to the [CISA KEV catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)
+  and [exploited to deploy the Flodrix botnet](https://www.trendmicro.com/en_us/research/25/f/langflow-vulnerability-flodric-botnet.html);
+  `CVE-2026-5027` (path-traversal → RCE) is [being exploited across ~7,000 exposed instances](https://www.bleepingcomputer.com/news/security/path-traversal-flaw-in-ai-dev-platform-langflow-exploited-in-attacks/).
+- **LangGraph checkpointer CVEs** — SQL injection and unsafe deserialization in
+  the SQLite/base checkpointers can chain to RCE via forged checkpoint rows.
+- **Supply-chain attacks** on the CI actions and packages the ecosystem depends
+  on (the tj-actions and LiteLLM incidents) mean a pinned-to-a-tag action or an
+  unpinned dependency is a real risk surface.
+
+These are exactly the things a framework-specific linter can catch before you
+ship. langdoctor ships the CVE data with the package and runs fully offline.
+
+## What it checks
+
+<!-- BEGIN check-table (generated from `langdoctor list-checks`) -->
+| ID | Category | Severity | What it catches |
+| --- | --- | --- | --- |
+| `LD101` | Known CVEs | high | SQL injection via metadata filter key in SQLite checkpointer |
+| `LD102` | Known CVEs | medium | Unsafe msgpack deserialization in checkpoint loading |
+| `LD103` | Known CVEs | medium | Unsafe JSON deserialization in checkpoint loading |
+| `LD104` | Known CVEs | high | Path traversal in legacy load_prompt functions |
+| `LD105` | Known CVEs | critical | Serialization-injection secret extraction in dumps/loads |
+| `LD106` | Known CVEs | critical 🔴KEV | Unauthenticated RCE in /api/v1/validate/code (Langflow) |
+| `LD107` | Known CVEs | medium | BaseCache deserialization of untrusted data may lead to RCE |
+| `LD108` | Known CVEs | high | RCE in "json" mode of JsonPlusSerializer |
+| `LD109` | Known CVEs | high | SQL injection in the SQLite store implementation |
+| `LD110` | Known CVEs | high | SQL injection via filter key in SqliteStore |
+| `LD111` | Known CVEs | high 🔴KEV | Path traversal → RCE via /api/v2/files upload (Langflow) |
+| `LD150` | Known CVEs | high | Langflow older than the current secure baseline (1.10.1) |
+| `LD201` | Checkpointer & state | high | MemorySaver used in a production-bound project |
+| `LD202` | Checkpointer & state | medium | SqliteSaver may collapse under write concurrency |
+| `LD203` | Checkpointer & state | high (heuristic) | Checkpoint history filtered by user-controlled input |
+| `LD204` | Checkpointer & state | medium | Compiled graph with interrupts has no checkpointer |
+| `LD301` | Graph & runtime config | medium | No recursion_limit configured for a LangGraph run |
+| `LD302` | Graph & runtime config | low (heuristic) | LLM client created without a timeout |
+| `LD303` | Graph & runtime config | info | Deprecated pre-1.0 LangChain import |
+| `LD304` | Graph & runtime config | high | Legacy load_prompt() usage |
+| `LD401` | Secrets & exposure | critical | Hardcoded API key in source |
+| `LD402` | Secrets & exposure | high | .env file present but not gitignored |
+| `LD403` | Secrets & exposure | critical | Langflow auto-login not explicitly disabled |
+| `LD501` | Hygiene | medium | Dependencies are not pinned |
+| `LD502` | Hygiene | medium | GitHub Actions uses an unpinned third-party action |
+<!-- END check-table -->
+
+Severities for CVE checks are derived from the CVSS score; `🔴KEV` marks
+[Known-Exploited](https://www.cisa.gov/known-exploited-vulnerabilities-catalog)
+vulnerabilities, which are always surfaced first.
+
+## CI integration
+
+### GitHub Action
+
+```yaml
+# .github/workflows/langdoctor.yml
+name: langdoctor
+on: [push, pull_request]
+permissions:
+  contents: read
+  security-events: write   # to upload SARIF
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: elaz48/langdoctor@v1
+        with:
+          fail-on: high
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: langdoctor.sarif
+```
+
+Findings show up in your repo's **Security → Code scanning** tab.
+
+### pre-commit
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/elaz48/langdoctor
+    rev: v0.1.0
+    hooks:
+      - id: langdoctor
+```
+
+### GitLab CI
+
+```yaml
+langdoctor:
+  image: python:3.12-slim
+  script:
+    - pip install langdoctor
+    - langdoctor --format sarif > gl-langdoctor.sarif
+  artifacts:
+    reports:
+      sast: gl-langdoctor.sarif
+```
+
+## Configuration
+
+Configure defaults in `pyproject.toml`; command-line flags take precedence.
+
+```toml
+[tool.langdoctor]
+fail-on = "high"            # critical | high | medium | low | never
+ignore  = ["LD203", "LD302"]
+exclude = ["examples", "vendor"]
+```
+
+Suppress a single finding inline — by LD id, CVE, or any alias:
+
+```python
+API_KEY = get_key()  # langdoctor: ignore=LD401
+```
+
+```text
+langgraph==1.0.5  # langdoctor: ignore=LD102
+```
+
+Suppressed findings are always reported as a `suppressed: N` count so nothing
+disappears silently.
+
+## Output formats
+
+`--format console` (default) · `json` · `sarif` · `markdown`
+
+- **sarif** — GitHub code scanning; `security-severity` carries the real CVSS.
+- **markdown** — paste straight into a PR or issue.
+- **json** — machine-readable, with a per-severity summary.
+
+Exit codes: `0` clean (or below `--fail-on`), `1` findings at/above threshold,
+`2` scan error. Heuristic checks never affect the exit code unless `--strict`.
+
+## What langdoctor is NOT
+
+- ❌ **Not a runtime guard.** It scans code and dependencies; it does not sit in
+  your request path.
+- ❌ **Not an LLM firewall.** It does no prompt-injection or content analysis.
+- ❌ **Not a replacement for Semgrep/Snyk.** It's the *framework-specific* layer
+  those miss — LangGraph/LangChain/Langflow footguns, by ID, with fixes.
+
+It is deterministic (no AI calls), offline (CVE data ships in the package), and
+zero-config.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+Requires Python 3.10+. See [`CLAUDE.md`](CLAUDE.md) for design principles, the
+check-ID conventions, and the "advisories are data" model.
+
+## License
+
+MIT © 2026 elaz48
+
+<sub>Topics: langgraph · langchain · langflow · security · sast · ai-agents · llm-security · devsecops · cli</sub>