devguard-scanner 0.1.0__tar.gz → 0.3.0__tar.gz

{devguard_scanner-0.1.0 → devguard_scanner-0.3.0}/.gitignore

@@ -1,6 +1,8 @@
 # Private planning material (kept out of the repository)
 docs/plan/
 docs/previous/
+DESIGN.md
+TASKS.md
 
 # Python
 .venv/

devguard_scanner-0.3.0/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/) and
+the project uses [semantic versioning](https://semver.org).
+
+## 0.3.0
+
+- The default drop folder for local scans (`DEVGUARD_API_LOCAL_ROOT`, and the folder `compose.yaml` mounts) is
+  now `~/devguard-scanner-data` instead of `~/devguard-scanner`. Move the folder, or set the variable to keep
+  the old location.
+- File locations use `devguard-scanner` (only the command is still `devguard`): config
+  `~/.config/devguard-scanner/config.toml` (the old `~/.config/devguard/config.toml` is still read if the new one
+  is missing), app data `~/.local/share/devguard-scanner/` (AI consent and cache, MCP audit log), and reports
+  `~/devguard-scanner/reports/` on every OS. In the container image the config is
+  `/etc/devguard-scanner/config.toml`.
+
+## 0.2.0
+
+Remote scanning, the HTTP API, and the container image.
+
+- `devguard scan https://github.com/OWNER/REPO [--ref REF]`: fetches one commit as a tarball (no `git`), extracts
+  it with a hardened extractor, scans it, and deletes it. Private repositories work with your own token
+  (`DEVGUARD_GITHUB_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN`).
+- The fetched archive is reconciled with the git tree, and files hidden by `export-ignore` are fetched and
+  scanned. New rule `DG-GIT-EXPORT-IGNORE-001` (high when the hidden files are triggers or flagged code).
+- Reports of remote scans carry a `source` section (repository, ref, commit). Markdown shows it, and SARIF uses
+  `versionControlProvenance`. The JSON field is optional, so existing consumers are unaffected.
+- `--stdout md|json|sarif`; new exit code `5` (repository could not be fetched); `devguard doctor` shows whether
+  a GitHub token is set.
+- HTTP API (`devguard-scanner[api]`, `devguard serve`): scans of public GitHub repositories with Swagger UI,
+  json/md/sarif output, a CI gate, per-scan worker processes with resource limits, rate limiting, and CDN
+  caching. Self-hosted instances can also scan local repositories linked (native) or bind-mounted read-only
+  (Docker) into a drop folder, without copying them.
+- Optional AI investigation through the API with the caller's own Anthropic or OpenAI key. The key is used in
+  memory only, and the endpoint is fixed by the server.
+- Optional MongoDB request log (`devguard-scanner[mongodb]`). It stores request metadata, the JSON report, and
+  the head of report.md, never the full report.md or AI keys, and expires records after 90 days by default.
+- Container image `ghcr.io/yilmazhasan/devguard-scanner` (non-root, no git, multi-arch, signed, SBOM), plus
+  `compose.yaml` and the Vercel deployment in `deploy/vercel/`.
+- Project URLs now point to `github.com/yilmazhasan/devguard-scanner`.
+- VS Code task findings (`DG-VSC-TASK-AUTORUN-001`, `DG-VSC-TASK-HIDDEN-001`) now point at the `runOn` or
+  `presentation` line instead of the task's opening `{`, so the report excerpt shows the offending setting.
+
+## 0.1.0
+
+First release.
+
+- Read-only scanner: no execution, no writes to the target, no symlink following, bounded reads and budgets.
+- Surface analyzers for VS Code (tasks, launch, settings, workspaces, MCP), Claude Code hooks and permissions, MCP
+  configs (Cursor, Gemini, Windsurf, …), dev containers, npm/yarn/pnpm/bun, Python packaging, git config/hooks/
+  submodules, direnv and `.env` files, auto-loaded tool configs, and README instructions.
+- 119 rules: content rules (YAML) for JavaScript/TypeScript, Python, shell, PowerShell/batch, AI instruction
+  files, and docs; hidden-content checks (bidi, invisible Unicode, off-screen code, encoded blobs); carriers
+  (executables, disguised files, archives, pickles); dependency sources and lockfiles.
+- Attack-chain correlation from automatic triggers to dangerous code, up to three hops.
+- Deterministic verdicts (`block` / `review` / `indicators` / `no-indicators`), Markdown, JSON, and SARIF reports.
+- Optional AI investigation with pluggable providers (Claude, OpenAI, OpenAI-compatible, Python plugins), consent,
+  budgets, read-only tools, citation verification, and caching.
+- MCP server with `scan_workspace`, `check_command`, findings, and rule tools.

{devguard_scanner-0.1.0 → devguard_scanner-0.3.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: devguard-scanner
-Version: 0.1.0
+Version: 0.3.0
 Summary: Scan untrusted code repositories for malware before you open, install, or run them. Files are analyzed as data and never executed.
-Project-URL: Homepage, https://github.com/yilmazhasan/dev-guard
-Project-URL: Documentation, https://github.com/yilmazhasan/dev-guard/tree/main/docs
-Project-URL: Issues, https://github.com/yilmazhasan/dev-guard/issues
-Project-URL: Changelog, https://github.com/yilmazhasan/dev-guard/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/yilmazhasan/devguard-scanner
+Project-URL: Documentation, https://github.com/yilmazhasan/devguard-scanner/tree/main/docs
+Project-URL: Issues, https://github.com/yilmazhasan/devguard-scanner/issues
+Project-URL: Changelog, https://github.com/yilmazhasan/devguard-scanner/blob/main/CHANGELOG.md
 Author: yilmazhasan
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -25,8 +25,13 @@ Requires-Dist: pydantic<3,>=2.7
 Requires-Dist: pyyaml<7,>=6.0.1
 Provides-Extra: anthropic
 Requires-Dist: anthropic<2,>=1.0; extra == 'anthropic'
+Provides-Extra: api
+Requires-Dist: fastapi<1,>=0.115; extra == 'api'
+Requires-Dist: uvicorn<1,>=0.30; extra == 'api'
 Provides-Extra: mcp
 Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
+Provides-Extra: mongodb
+Requires-Dist: pymongo<5,>=4.8; extra == 'mongodb'
 Provides-Extra: openai
 Requires-Dist: openai<4,>=1.50; extra == 'openai'
 Description-Content-Type: text/markdown
@@ -60,7 +65,7 @@ Findings: 5 (1 critical, 2 high, 1 medium, 1 low)
   - [critical] Automatic trigger reaches dangerous code (package.json:5)
   - [high] Browser profile data targeted (lib/collect.js:7)
   - [high] Cryptocurrency wallet data targeted (lib/collect.js:10)
-Report (md): ~/.local/share/devguard/reports/interview-task-1a2b3c4d/latest/report.md
+Report (md): ~/devguard-scanner/reports/interview-task-1a2b3c4d/latest/report.md
 ```
 
 | Verdict | Meaning |
@@ -72,12 +77,39 @@ Report (md): ~/.local/share/devguard/reports/interview-task-1a2b3c4d/latest/repo
 
 Exit code `1` means findings at or above `--fail-on` (default `high`), so it works as a CI gate.
 
+## Scan a GitHub repository without cloning it
+
+```bash
+devguard scan https://github.com/owner/repo          # add --ref BRANCH|TAG|SHA
+```
+
+The repository is downloaded into a temporary directory, scanned, and deleted. `git` is never run, so clone-time
+exploits and hooks cannot trigger, and the files never sit in a folder your IDE could open. Private repositories
+work with your own token (`GH_TOKEN`, `GITHUB_TOKEN`, or `DEVGUARD_GITHUB_TOKEN`).
+
+## No install: hosted API or Docker
+
+```bash
+# hosted API (public repositories), Swagger UI at https://devguard-scanner.vercel.app/docs
+curl -s 'https://devguard-scanner.vercel.app/v1/scans/github/owner/repo?format=md'
+
+# one-off scan in a throwaway container
+docker run --rm ghcr.io/yilmazhasan/devguard-scanner scan https://github.com/owner/repo --stdout md
+
+# self-hosted API, plus local scans of anything you copy into ~/devguard-scanner-data (mounted read-only)
+docker compose up -d
+```
+
+See the [API guide](docs/api.md) and the [Docker guide](docs/docker.md). Optional AI explanations work with
+your own provider key; the server never stores it.
+
 ## More
 
 - [Getting started](docs/getting-started.md): options, reports, exit codes
 - [AI investigation](docs/ai.md): optional explanations from Claude, OpenAI, Gemini, or a local model
 - [Provider plugins](docs/plugins.md): connect any LLM with a small Python file
 - [MCP server](docs/mcp.md): let Claude Code, Cursor, or Copilot check a repo before acting on it
+- [HTTP API](docs/api.md) · [Docker](docs/docker.md): scan without installing, or self-host
 - [CI and pre-commit](docs/ci.md) · [Configuration](docs/configuration.md) · [How it works](docs/how-it-works.md)
 - [Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md)
 

{devguard_scanner-0.1.0 → devguard_scanner-0.3.0}/README.md

@@ -27,7 +27,7 @@ Findings: 5 (1 critical, 2 high, 1 medium, 1 low)
   - [critical] Automatic trigger reaches dangerous code (package.json:5)
   - [high] Browser profile data targeted (lib/collect.js:7)
   - [high] Cryptocurrency wallet data targeted (lib/collect.js:10)
-Report (md): ~/.local/share/devguard/reports/interview-task-1a2b3c4d/latest/report.md
+Report (md): ~/devguard-scanner/reports/interview-task-1a2b3c4d/latest/report.md
 ```
 
 | Verdict | Meaning |
@@ -39,12 +39,39 @@ Report (md): ~/.local/share/devguard/reports/interview-task-1a2b3c4d/latest/repo
 
 Exit code `1` means findings at or above `--fail-on` (default `high`), so it works as a CI gate.
 
+## Scan a GitHub repository without cloning it
+
+```bash
+devguard scan https://github.com/owner/repo          # add --ref BRANCH|TAG|SHA
+```
+
+The repository is downloaded into a temporary directory, scanned, and deleted. `git` is never run, so clone-time
+exploits and hooks cannot trigger, and the files never sit in a folder your IDE could open. Private repositories
+work with your own token (`GH_TOKEN`, `GITHUB_TOKEN`, or `DEVGUARD_GITHUB_TOKEN`).
+
+## No install: hosted API or Docker
+
+```bash
+# hosted API (public repositories), Swagger UI at https://devguard-scanner.vercel.app/docs
+curl -s 'https://devguard-scanner.vercel.app/v1/scans/github/owner/repo?format=md'
+
+# one-off scan in a throwaway container
+docker run --rm ghcr.io/yilmazhasan/devguard-scanner scan https://github.com/owner/repo --stdout md
+
+# self-hosted API, plus local scans of anything you copy into ~/devguard-scanner-data (mounted read-only)
+docker compose up -d
+```
+
+See the [API guide](docs/api.md) and the [Docker guide](docs/docker.md). Optional AI explanations work with
+your own provider key; the server never stores it.
+
 ## More
 
 - [Getting started](docs/getting-started.md): options, reports, exit codes
 - [AI investigation](docs/ai.md): optional explanations from Claude, OpenAI, Gemini, or a local model
 - [Provider plugins](docs/plugins.md): connect any LLM with a small Python file
 - [MCP server](docs/mcp.md): let Claude Code, Cursor, or Copilot check a repo before acting on it
+- [HTTP API](docs/api.md) · [Docker](docs/docker.md): scan without installing, or self-host
 - [CI and pre-commit](docs/ci.md) · [Configuration](docs/configuration.md) · [How it works](docs/how-it-works.md)
 - [Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md)
 

{devguard_scanner-0.1.0 → devguard_scanner-0.3.0}/docs/README.md

@@ -6,10 +6,12 @@
 | [Configuration](configuration.md) | The user config file, every option, limits, exclusions |
 | [AI investigation](ai.md) | Enabling the optional AI layer, provider profiles (Claude, OpenAI, Gemini, local), consent, costs |
 | [Provider plugins](plugins.md) | Writing your own LLM provider in Python, testing it, sharing it |
+| [HTTP API](api.md) | The hosted and self-hosted API: endpoints, formats, limits, AI with your own key, request log |
+| [Docker](docker.md) | One-off scans in a container, self-hosting, the local drop folder |
 | [MCP server](mcp.md) | Using DevGuard from Claude Code, Cursor, VS Code Copilot, Gemini CLI |
 | [CI and pre-commit](ci.md) | GitHub Actions, SARIF upload, pre-commit hook |
 | [How it works](how-it-works.md) | Pipeline, triggers and attack chains, what is and is not detected |
 | [Rules](rules.md) | Rule catalogue, writing a detection rule |
 | [Threat reference](threats.md) | The `TC-xx` threat identifiers that rules reference |
 | [Dependencies](dependencies.md) | Why each runtime dependency exists |
-| [Releasing](releasing.md) | Publishing to PyPI (maintainers) |
+| [Releasing](releasing.md) | Publishing to PyPI and GHCR, deploying the hosted API (maintainers) |

{devguard_scanner-0.1.0 → devguard_scanner-0.3.0}/pyproject.toml

@@ -31,12 +31,14 @@ dependencies = [
 anthropic = ["anthropic>=1.0,<2"]
 openai = ["openai>=1.50,<4"]
 mcp = ["mcp>=2.3,<3"]
+api = ["fastapi>=0.115,<1", "uvicorn>=0.30,<1"]
+mongodb = ["pymongo>=4.8,<5"]
 
 [project.urls]
-Homepage = "https://github.com/yilmazhasan/dev-guard"
-Documentation = "https://github.com/yilmazhasan/dev-guard/tree/main/docs"
-Issues = "https://github.com/yilmazhasan/dev-guard/issues"
-Changelog = "https://github.com/yilmazhasan/dev-guard/blob/main/CHANGELOG.md"
+Homepage = "https://github.com/yilmazhasan/devguard-scanner"
+Documentation = "https://github.com/yilmazhasan/devguard-scanner/tree/main/docs"
+Issues = "https://github.com/yilmazhasan/devguard-scanner/issues"
+Changelog = "https://github.com/yilmazhasan/devguard-scanner/blob/main/CHANGELOG.md"
 
 [project.scripts]
 devguard = "devguard.cli:main"
@@ -52,6 +54,7 @@ dev = [
     "ruff>=0.6",
     "mypy>=1.11",
     "types-PyYAML",
+    "httpx>=0.27",  # FastAPI TestClient
 ]
 
 [build-system]

{devguard_scanner-0.1.0 → devguard_scanner-0.3.0}/src/devguard/__init__.py

@@ -1,5 +1,5 @@
 """DevGuard: pre-open security scanner for untrusted code workspaces."""
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 RULESET_VERSION = "2026.10.0"
 SCHEMA_VERSION = "1"

{devguard_scanner-0.1.0 → devguard_scanner-0.3.0}/src/devguard/ai/registry.py

@@ -93,7 +93,13 @@ def available_entry_points() -> dict[str, str]:
     return out
 
 
-def load_provider(cfg: AIConfig, profile_name: str | None, target: Path | None) -> LoadedProvider:
+def load_provider(
+    cfg: AIConfig,
+    profile_name: str | None,
+    target: Path | None,
+    secrets: dict[str, str] | None = None,
+) -> LoadedProvider:
+    """Load a profile's provider. `secrets` supplies already-resolved values (an API caller's own key)."""
     name = profile_name or cfg.default_profile
     if not name:
         raise ProviderError("no AI profile selected: pass --ai-profile or set ai.default_profile in your user config")
@@ -106,6 +112,8 @@ def load_provider(cfg: AIConfig, profile_name: str | None, target: Path | None)
     settings["model"] = profile.model
     for key, ref in profile.secrets.items():
         settings[key] = resolve_secret(ref)
+    provided = dict(secrets or {})
+    settings.update(provided)
     if profile.provider == "python":
         factory, origin = _load_file_plugin(profile.plugin, target)
     else:
@@ -118,7 +126,11 @@ def load_provider(cfg: AIConfig, profile_name: str | None, target: Path | None)
         if not hasattr(provider, attr):
             raise ProviderError(f"provider {profile.provider!r} does not implement AIProvider ({attr} missing)")
     return LoadedProvider(
-        provider, name, profile, origin, {k: v for k, v in settings.items() if k not in profile.secrets}
+        provider,
+        name,
+        profile,
+        origin,
+        {k: v for k, v in settings.items() if k not in profile.secrets and k not in provided},
     )
 
 

{devguard_scanner-0.1.0 → devguard_scanner-0.3.0}/src/devguard/ai/run.py

@@ -51,15 +51,20 @@ def run_ai(
     assume_consent: bool,
     use_cache: bool = True,
     ask: Callable[[str], bool] | None = None,
+    secrets: dict[str, str] | None = None,
 ) -> AIReport:
-    """Run the AI stage. Never raises: every failure becomes AIReport(status="failed"/"skipped")."""
+    """Run the AI stage. Never raises: every failure becomes AIReport(status="failed"/"skipped").
+
+    `secrets` passes already-resolved provider secrets (the API's per-request key) without touching the
+    environment, so concurrent requests never see each other's keys.
+    """
     try:
         cfg = AIConfig.model_validate(ai_settings)
     except Exception as exc:
         return AIReport(status="failed", error=f"invalid [ai] configuration: {exc}")
     target = Path(outcome.fs.root)
     try:
-        loaded = load_provider(cfg, profile, target)
+        loaded = load_provider(cfg, profile, target, secrets)
     except ProviderError as exc:
         return AIReport(status="failed", profile=profile or cfg.default_profile, error=str(exc))
     caps = loaded.provider.capabilities()

devguard_scanner-0.3.0/src/devguard/analyzers/source.py

@@ -0,0 +1,40 @@
+"""Checks on how a remote target was delivered (TC-06.8). Only runs for scans of fetched repositories."""
+
+from __future__ import annotations
+
+from devguard.analyzers.base import AnalysisContext
+from devguard.core.models import Evidence, Finding, Severity, SourceInfo
+from devguard.core.redact import visible
+from devguard.rules.catalog import build_finding, rule
+
+R_EXPORT_IGNORE = rule(
+    "DG-GIT-EXPORT-IGNORE-001",
+    "Files hidden from the repository's download archive",
+    "info",
+    "high",
+    "vcs",
+    "TC-06.8",
+    "Some files exist in the git tree but are left out of GitHub's download archive (`export-ignore` in "
+    ".gitattributes). `git clone` still delivers them. DevGuard fetched them separately and scanned them. "
+    "When the hidden files contain automatic triggers or dangerous code, hiding them from archive-based "
+    "reviews looks deliberate.",
+    "Libraries (PHP packages in particular) routinely export-ignore tests, CI files, and docs to keep their "
+    "release archives small.",
+    "If the hidden files are triggers or flagged code, treat the repository as hostile: someone reviewing the "
+    "ZIP download would not have seen them.",
+)
+
+
+def source_findings(source: SourceInfo | None, ctx: AnalysisContext, findings: list[Finding]) -> list[Finding]:
+    if source is None or not source.hidden_from_archive:
+        return []
+    hidden = set(source.hidden_from_archive)
+    trigger_paths = {t.path for t in ctx.triggers} | {r for t in ctx.triggers for r in t.references}
+    flagged = {f.primary_path for f in findings if f.severity.rank >= Severity.MEDIUM.rank}
+    suspicious = sorted(hidden & (trigger_paths | flagged))
+    shown = suspicious or sorted(hidden)
+    evidence = [Evidence(path=visible(p)) for p in shown[:20]]
+    detail = f"{len(hidden)} file(s) are missing from the archive."
+    if suspicious:
+        detail += f" {len(suspicious)} of them are automatic triggers, run by one, or flagged by other rules."
+    return [build_finding(R_EXPORT_IGNORE.id, evidence, severity=Severity.HIGH if suspicious else None, detail=detail)]

{devguard_scanner-0.1.0 → devguard_scanner-0.3.0}/src/devguard/analyzers/surfaces/vscode.py

@@ -224,19 +224,23 @@ class VSCodeAnalyzer:
             if is_auto:
                 shown = "; ".join(make_excerpt(c, limit=120) for _, c, _ in commands) or "(no command)"
                 direct = _run_on(t) == "folderOpen"
+                # Anchor on the line that makes the task auto-run, not the object's opening "{".
+                ro = t.get("runOptions")
+                anchor = (ro.get("runOn") if ro is not None else None) or label_node or t
                 out.append(
                     build_finding(
                         R_AUTORUN.id,
-                        [fv.evidence_at_line(t.line)],
+                        [fv.evidence_at_line(anchor.line)],
                         detail=f"Task {make_excerpt(label, limit=80)!r}"
                         f"{'' if direct else ' (dependency of a folder-open task)'} runs: {shown}.",
                     )
                 )
-                if _hides_output(t):
+                hiding = _hiding_option(t)
+                if hiding is not None:
                     out.append(
                         build_finding(
                             R_HIDDEN_TASK.id,
-                            [fv.evidence_at_line(t.line)],
+                            [fv.evidence_at_line(hiding.line)],
                             detail=f"Task {make_excerpt(label, limit=80)!r}.",
                         )
                     )
@@ -459,18 +463,21 @@ def _run_on(task: Node) -> str | None:
     return run_on.value if run_on is not None and isinstance(run_on.value, str) else None
 
 
-def _hides_output(task: Node) -> bool:
+def _hiding_option(task: Node) -> Node | None:
+    """The `presentation` option that hides the task's terminal output, if any."""
     pres = task.get("presentation")
     if pres is None:
-        return False
+        return None
     reveal = pres.get("reveal")
+    if reveal is not None and reveal.value == "never":
+        return reveal
     echo = pres.get("echo")
+    if echo is not None and echo.value is False:
+        return echo
     close = pres.get("close")
-    return (
-        (reveal is not None and reveal.value == "never")
-        or (echo is not None and echo.value is False)
-        or (close is not None and close.value is True)
-    )
+    if close is not None and close.value is True:
+        return close
+    return None
 
 
 def _task_commands(task: Node) -> list[tuple[str, str, int]]:

devguard_scanner-0.3.0/src/devguard/api/__init__.py

@@ -0,0 +1,5 @@
+"""DevGuard HTTP API (extra `devguard-scanner[api]`). Start it with `devguard serve`.
+
+This package must stay importable without FastAPI: the worker process (`devguard.api.worker`) only needs the
+base install. FastAPI is imported by `devguard.api.app` alone.
+"""