codeintely-cli 0.1.0__py3-none-any.whl

codeintely_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

codeintely_cli/binaries.py

@@ -0,0 +1,178 @@
+"""Auto-installs gitleaks/osv-scanner/trivy on first use, so a plain
+`pip install codeintely-cli` gets full coverage (secrets, dependency CVEs,
+IaC misconfig) without a user separately installing three more tools by
+hand — the actual point of "include gitleaks/osv-scanner/trivy" rather
+than just reporting them as skipped.
+
+An existing PATH install is always preferred over downloading a second
+copy (shutil.which() checked first) — this only downloads when nothing
+is already available. Downloaded binaries are cached under
+~/.codeintely/bin/ and reused on every later run; only the very first
+`codeintely scan` after install pays the download cost.
+
+Versions are pinned to the exact same releases backend/Dockerfile uses
+in production (gitleaks v8.21.2, osv-scanner v2.4.0, trivy v0.74.0) —
+same detection behavior locally as the hosted GitHub App, not
+independently-drifting versions. Asset names/archive layouts below were
+confirmed against the real GitHub releases for these exact versions, not
+assumed from a naming convention.
+
+osv-scanner is pinned to v2.4.0 specifically, not the also-real v1.9.2:
+confirmed live that scanners.py's `scan source ...` invocation has no
+`source` subcommand in v1.9.2 (real syntax there is just `scan
+[directory]`) — it silently produces zero findings instead of erroring,
+since the failed run leaves the pre-created output file empty and the
+caller reads "empty file" as "clean scan." v2.4.0 is what this was
+actually written and tested against.
+"""
+
+import io
+import logging
+import platform
+import shutil
+import stat
+import sys
+import tarfile
+import urllib.error
+import urllib.request
+import zipfile
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+CACHE_DIR = Path.home() / ".codeintely" / "bin"
+DOWNLOAD_TIMEOUT_SECONDS = 180  # trivy's Windows build alone is ~170MB
+
+GITLEAKS_VERSION = "8.21.2"
+OSV_SCANNER_VERSION = "2.4.0"
+TRIVY_VERSION = "0.74.0"
+
+
+def _os_arch() -> tuple[str | None, str | None]:
+    system = platform.system()  # "Windows" | "Linux" | "Darwin"
+    machine = platform.machine().lower()
+    if machine in ("amd64", "x86_64"):
+        arch = "x64"
+    elif machine in ("arm64", "aarch64"):
+        arch = "arm64"
+    else:
+        arch = None  # a real, if rare, unsupported case (e.g. 32-bit) — no asset built for it
+    return (system if system in ("Windows", "Linux", "Darwin") else None), arch
+
+
+def _gitleaks_asset(system: str, arch: str) -> str | None:
+    os_name = {"Windows": "windows", "Linux": "linux", "Darwin": "darwin"}[system]
+    # Confirmed live: this exact pinned version has no windows_arm64 build
+    # (later releases added one) — a real, narrow gap, not a bug.
+    if system == "Windows" and arch == "arm64":
+        return None
+    ext = "zip" if system == "Windows" else "tar.gz"
+    return f"gitleaks_{GITLEAKS_VERSION}_{os_name}_{arch}.{ext}"
+
+
+def _osv_scanner_asset(system: str, arch: str) -> str | None:
+    os_name = {"Windows": "windows", "Linux": "linux", "Darwin": "darwin"}[system]
+    arch_name = "amd64" if arch == "x64" else "arm64"
+    ext = ".exe" if system == "Windows" else ""
+    return f"osv-scanner_{os_name}_{arch_name}{ext}"
+
+
+def _trivy_asset(system: str, arch: str) -> str | None:
+    # Confirmed live: real, inconsistent-but-real casing per OS — "Linux"
+    # and "macOS" are capitalized, "windows" isn't.
+    os_name = {"Windows": "windows", "Linux": "Linux", "Darwin": "macOS"}[system]
+    arch_name = "64bit" if arch == "x64" else "ARM64"
+    ext = "zip" if system == "Windows" else "tar.gz"
+    return f"trivy_{TRIVY_VERSION}_{os_name}-{arch_name}.{ext}"
+
+
+# {tool_name: (release_base_url, asset_fn, is_raw_binary)} — is_raw_binary
+# distinguishes osv-scanner (the GitHub asset itself IS the binary, no
+# archive) from gitleaks/trivy (a .zip/.tar.gz to extract from).
+_TOOLS = {
+    "gitleaks": (
+        f"https://github.com/gitleaks/gitleaks/releases/download/v{GITLEAKS_VERSION}",
+        _gitleaks_asset, False,
+    ),
+    "osv-scanner": (
+        f"https://github.com/google/osv-scanner/releases/download/v{OSV_SCANNER_VERSION}",
+        _osv_scanner_asset, True,
+    ),
+    "trivy": (
+        f"https://github.com/aquasecurity/trivy/releases/download/v{TRIVY_VERSION}",
+        _trivy_asset, False,
+    ),
+}
+
+
+def _download(url: str) -> bytes | None:
+    try:
+        with urllib.request.urlopen(url, timeout=DOWNLOAD_TIMEOUT_SECONDS) as resp:
+            return resp.read()
+    except (urllib.error.URLError, OSError, TimeoutError):
+        return None
+
+
+def _extract_binary(archive_bytes: bytes, asset_name: str, member_name: str, dest_path: Path) -> bool:
+    try:
+        if asset_name.endswith(".zip"):
+            with zipfile.ZipFile(io.BytesIO(archive_bytes)) as zf:
+                with zf.open(member_name) as src, open(dest_path, "wb") as dst:
+                    shutil.copyfileobj(src, dst)
+        elif asset_name.endswith(".tar.gz"):
+            with tarfile.open(fileobj=io.BytesIO(archive_bytes), mode="r:gz") as tf:
+                member = tf.getmember(member_name)
+                extracted = tf.extractfile(member)
+                if extracted is None:
+                    return False
+                with extracted, open(dest_path, "wb") as dst:
+                    shutil.copyfileobj(extracted, dst)
+        else:
+            # osv-scanner: the downloaded asset already IS the binary.
+            dest_path.write_bytes(archive_bytes)
+    except (zipfile.BadZipFile, tarfile.TarError, KeyError, OSError):
+        return False
+    return True
+
+
+def ensure_binary(name: str) -> str | None:
+    """Returns a usable path to `name` — an existing PATH install if
+    found, otherwise auto-downloads the pinned version into
+    ~/.codeintely/bin/ (reused on every later call/run). Returns None
+    only when neither a PATH install nor a download succeeds
+    (unsupported platform/architecture, no network, GitHub unreachable)
+    — callers treat that the same as "not installed."
+    """
+    existing = shutil.which(name)
+    if existing:
+        return existing
+
+    exe_name = f"{name}.exe" if sys.platform == "win32" else name
+    cached = CACHE_DIR / exe_name
+    if cached.is_file():
+        return str(cached)
+
+    system, arch = _os_arch()
+    if system is None or arch is None:
+        return None
+
+    base_url, asset_fn, is_raw_binary = _TOOLS[name]
+    asset = asset_fn(system, arch)
+    if asset is None:
+        return None
+
+    print(f"codeintely: downloading {name} (one-time, cached under {CACHE_DIR})...", file=sys.stderr)
+    data = _download(f"{base_url}/{asset}")
+    if data is None:
+        logger.error("Could not download %s from %s/%s", name, base_url, asset)
+        return None
+
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    member_name = exe_name if not is_raw_binary else asset
+    if not _extract_binary(data, asset, member_name, cached):
+        logger.error("Downloaded %s but couldn't extract/save it", name)
+        return None
+
+    if sys.platform != "win32":
+        cached.chmod(cached.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+    return str(cached)

codeintely_cli/main.py

@@ -0,0 +1,76 @@
+"""`codeintely` CLI entry point (P2d). See pyproject.toml's [project.scripts]."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__, output, scanners
+
+# Windows consoles commonly default stdout to a legacy codepage (cp1252)
+# that can't encode the ✓ in a clean report or non-ASCII bytes a scanner
+# might legitimately emit (a file path, a finding message) — confirmed
+# live: a bare `print()` of this module's own "No findings" line crashed
+# with UnicodeEncodeError before this reconfigure. errors="replace" over a
+# stricter mode since a scan report should never crash on output — a
+# mangled character is a much smaller problem than the tool being unusable
+# on a stock Windows terminal.
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+SEVERITY_ORDER = output.SEVERITY_ORDER
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="codeintely",
+        description="CodeIntely local security scanner — the same custom rule pack the GitHub App uses, run locally.",
+    )
+    parser.add_argument("--version", action="version", version=f"codeintely-cli {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    scan = subparsers.add_parser("scan", help="Scan a local directory (default: current directory).")
+    scan.add_argument("path", nargs="?", default=".", help="Directory to scan (default: .)")
+    scan.add_argument("--format", choices=["text", "json"], default="text", help="Output format (default: text)")
+    scan.add_argument(
+        "--severity-threshold", choices=SEVERITY_ORDER, default="HIGH",
+        help="Exit non-zero only when a finding at or above this severity exists (default: HIGH) — matches "
+             "the same bar the GitHub App's PR check run uses.",
+    )
+    scan.add_argument("--no-color", action="store_true", help="Disable ANSI color in text output.")
+    return parser
+
+
+def _exceeds_threshold(findings: list[dict], threshold: str) -> bool:
+    threshold_index = SEVERITY_ORDER.index(threshold)
+    return any(
+        SEVERITY_ORDER.index(f["severity"]) <= threshold_index
+        for f in findings if f["severity"] in SEVERITY_ORDER
+    )
+
+
+def run_scan(args) -> int:
+    target_dir = Path(args.path).resolve()
+    if not target_dir.is_dir():
+        print(f"error: {target_dir} is not a directory", file=sys.stderr)
+        return 2
+
+    findings, skipped = scanners.run_all(target_dir)
+
+    if args.format == "json":
+        print(output.render_json(findings, skipped, target_dir))
+    else:
+        print(output.render_text(findings, skipped, target_dir, use_color=not args.no_color))
+
+    return 1 if _exceeds_threshold(findings, args.severity_threshold) else 0
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    if args.command == "scan":
+        sys.exit(run_scan(args))
+
+
+if __name__ == "__main__":
+    main()

codeintely_cli/output.py

@@ -0,0 +1,63 @@
+"""Text/JSON reporting for the CLI. Stdlib-only ANSI coloring — no `rich`/
+`click` dependency, keeping `pip install codeintely-cli` lean.
+"""
+
+import json
+import sys
+
+SEVERITY_ORDER = ["CRITICAL", "HIGH", "MEDIUM", "LOW"]
+_SEVERITY_COLOR = {"CRITICAL": "\033[1;31m", "HIGH": "\033[31m", "MEDIUM": "\033[33m", "LOW": "\033[90m"}
+_RESET = "\033[0m"
+_BOLD = "\033[1m"
+
+
+def _supports_color() -> bool:
+    # Modern Windows terminals (10+) handle ANSI codes fine when attached
+    # to a real console; the only case to avoid coloring is output being
+    # redirected/piped (a file, `| less`, CI log capture), where isatty()
+    # is False on every platform.
+    return sys.stdout.isatty()
+
+
+def render_text(findings: list[dict], skipped: list[str], target_dir, use_color: bool) -> str:
+    lines = []
+    color = use_color and _supports_color()
+
+    def c(code, text):
+        return f"{code}{text}{_RESET}" if color else text
+
+    lines.append(c(_BOLD, f"codeintely scan — {target_dir}"))
+    lines.append("")
+
+    if skipped:
+        lines.append(f"Skipped (not installed): {', '.join(skipped)} — install for fuller coverage.")
+        lines.append("")
+
+    if not findings:
+        lines.append(c("\033[32m", "No findings. ✓"))
+        return "\n".join(lines)
+
+    findings_sorted = sorted(
+        findings, key=lambda f: SEVERITY_ORDER.index(f["severity"]) if f["severity"] in SEVERITY_ORDER else 99
+    )
+    for f in findings_sorted:
+        sev = f["severity"]
+        sev_label = c(_SEVERITY_COLOR.get(sev, ""), f"[{sev}]")
+        location = f"{f['file_path']}:{f['line_number']}" if f.get("line_number") else f["file_path"]
+        lines.append(f"{sev_label} {c(_BOLD, f['rule_id'])} ({f['scanner']}) — {location}")
+        lines.append(f"    {f['message']}")
+        lines.append("")
+
+    counts = {sev: sum(1 for f in findings if f["severity"] == sev) for sev in SEVERITY_ORDER}
+    summary = ", ".join(f"{counts[s]} {s}" for s in SEVERITY_ORDER if counts[s])
+    lines.append(c(_BOLD, f"{len(findings)} finding(s): {summary}"))
+    return "\n".join(lines)
+
+
+def render_json(findings: list[dict], skipped: list[str], target_dir) -> str:
+    return json.dumps({
+        "target": str(target_dir),
+        "skipped_scanners": skipped,
+        "finding_count": len(findings),
+        "findings": findings,
+    }, indent=2)

codeintely_cli/rules/appsec_breadth.yaml

@@ -0,0 +1,220 @@
+rules:
+  # --- SSRF, command injection, insecure deserialization, path traversal ---
+  #
+  # These four use Semgrep's taint-mode (mode: taint), not used anywhere
+  # else in this rule pack until now — evaluated and validated directly
+  # (real semgrep runs against real tainted/untainted fixtures, not just
+  # read the docs) per PLANNING.md's own prerequisite note that plain
+  # pattern-matching alone over-flags this vulnerability class (e.g. ANY
+  # `requests.get($URL)` call, tainted or not) while taint-mode only fires
+  # when a source (request input) actually reaches a sink (the dangerous
+  # call), which is the real question for all four of these. Confirmed
+  # empirically that Semgrep's taint engine correctly tracks propagation
+  # through os.path.join(), f-string building, and variable reassignment —
+  # not just direct source-to-sink calls.
+  #
+  # The same `pattern-sources` list is repeated across all four rules
+  # rather than factored into a YAML anchor/alias — semgrep's own rule
+  # parser rejects `pattern-sources: *anchor` ("Expected a list for
+  # pattern-sources") even though it's valid YAML that PyYAML resolves
+  # fine, confirmed by testing `semgrep --validate` directly.
+
+  - id: python-ssrf-tainted-url
+    mode: taint
+    languages: [python]
+    severity: ERROR
+    message: >-
+      A URL built from request input reaches an outbound HTTP call with no
+      visible allowlist/validation in between. If an attacker controls this
+      URL, they can make this server issue requests to internal-only hosts
+      (cloud metadata endpoints, internal admin APIs, localhost services) —
+      Server-Side Request Forgery. Validate the URL against an explicit
+      allowlist of permitted hosts/schemes before making the request, not
+      just that it parses as a URL.
+    metadata:
+      owasp_category: "A10:2021 - Server-Side Request Forgery"
+      cwe: "CWE-918"
+      internal_severity: CRITICAL
+    pattern-sources:
+      - pattern: request.GET.get(...)
+      - pattern: request.GET[...]
+      - pattern: request.POST.get(...)
+      - pattern: request.POST[...]
+      - pattern: request.data.get(...)
+      - pattern: request.data[...]
+      - pattern: request.query_params.get(...)
+    pattern-sinks:
+      - pattern: requests.get(...)
+      - pattern: requests.post(...)
+      - pattern: requests.put(...)
+      - pattern: requests.delete(...)
+      - pattern: requests.head(...)
+      - pattern: requests.patch(...)
+      - pattern: requests.request(...)
+      - pattern: urllib.request.urlopen(...)
+      - pattern: httpx.get(...)
+      - pattern: httpx.post(...)
+
+  - id: python-command-injection-shell-true
+    mode: taint
+    languages: [python]
+    severity: ERROR
+    message: >-
+      Request input reaches a shell command execution call (`os.system` —
+      always shell-interpreted — or `subprocess.*` with `shell=True`). With
+      `shell=True`, the string is parsed by a real shell, so shell
+      metacharacters in the tainted value (`;`, `|`, `&&`, backticks) let an
+      attacker run arbitrary commands, not just influence one argument.
+      Pass a list of arguments to `subprocess.run`/`.call`/`.Popen` with
+      `shell=False` (the default) instead — a list's elements are never
+      shell-interpreted, so this class of injection isn't possible even
+      with attacker-controlled values in it.
+    metadata:
+      owasp_category: "A03:2021 - Injection"
+      cwe: "CWE-78"
+      internal_severity: CRITICAL
+    pattern-sources:
+      - pattern: request.GET.get(...)
+      - pattern: request.GET[...]
+      - pattern: request.POST.get(...)
+      - pattern: request.POST[...]
+      - pattern: request.data.get(...)
+      - pattern: request.data[...]
+      - pattern: request.query_params.get(...)
+    pattern-sinks:
+      - pattern: os.system(...)
+      - patterns:
+          - pattern: subprocess.run(...)
+          - pattern-either:
+              - pattern: subprocess.run(..., shell=True, ...)
+      - patterns:
+          - pattern: subprocess.call(...)
+          - pattern-either:
+              - pattern: subprocess.call(..., shell=True, ...)
+      - patterns:
+          - pattern: subprocess.Popen(...)
+          - pattern-either:
+              - pattern: subprocess.Popen(..., shell=True, ...)
+      - patterns:
+          - pattern: subprocess.check_output(...)
+          - pattern-either:
+              - pattern: subprocess.check_output(..., shell=True, ...)
+      - patterns:
+          - pattern: subprocess.check_call(...)
+          - pattern-either:
+              - pattern: subprocess.check_call(..., shell=True, ...)
+
+  - id: python-pickle-loads-tainted
+    mode: taint
+    languages: [python]
+    severity: ERROR
+    message: >-
+      Request input reaches `pickle.loads()`/`pickle.load()`. Unpickling is
+      not just parsing — it can execute arbitrary code during
+      deserialization (via a crafted object's `__reduce__`), so unpickling
+      anything an attacker can influence is equivalent to running their
+      code. Never unpickle request-derived data; use a safe format (JSON)
+      for anything crossing a trust boundary, or cryptographically sign the
+      pickled payload and verify the signature before unpickling if pickle
+      is genuinely required.
+    metadata:
+      owasp_category: "A08:2021 - Software and Data Integrity Failures"
+      cwe: "CWE-502"
+      internal_severity: CRITICAL
+    pattern-sources:
+      - pattern: request.GET.get(...)
+      - pattern: request.GET[...]
+      - pattern: request.POST.get(...)
+      - pattern: request.POST[...]
+      - pattern: request.data.get(...)
+      - pattern: request.data[...]
+      - pattern: request.query_params.get(...)
+    pattern-sinks:
+      - pattern: pickle.loads(...)
+      - pattern: pickle.load(...)
+
+  - id: python-path-traversal-tainted
+    mode: taint
+    languages: [python]
+    severity: ERROR
+    message: >-
+      Request input reaches `open()` (directly or via `os.path.join()`/an
+      f-string building the path) with no visible traversal check. A value
+      like `../../etc/passwd` or an absolute path lets an attacker read (or
+      write, for a write-mode open) any file the process can access, not
+      just files under the intended directory. Resolve the final path
+      (`os.path.realpath`/`Path.resolve()`) and verify it's still inside
+      the intended base directory before opening, or map the input against
+      an explicit allowlist of permitted filenames instead of using it in
+      the path directly.
+    metadata:
+      owasp_category: "A01:2021 - Broken Access Control"
+      cwe: "CWE-22"
+      internal_severity: HIGH
+    pattern-sources:
+      - pattern: request.GET.get(...)
+      - pattern: request.GET[...]
+      - pattern: request.POST.get(...)
+      - pattern: request.POST[...]
+      - pattern: request.data.get(...)
+      - pattern: request.data[...]
+      - pattern: request.query_params.get(...)
+    pattern-sinks:
+      - pattern: open(...)
+
+  # --- Insecure deserialization (non-taint half) ------------------------
+  #
+  # yaml.load() without a safe Loader is dangerous regardless of where the
+  # input came from (PyYAML's default/full Loader can construct arbitrary
+  # Python objects from the YAML content itself) — a single dangerous call
+  # shape, not a data-flow question, matching the existing style of
+  # django-debug-true/sbom.py's setup.py auditor rather than taint-mode.
+
+  - id: python-insecure-yaml-load
+    languages: [python]
+    severity: ERROR
+    message: >-
+      `yaml.load()` without an explicit safe `Loader` can construct
+      arbitrary Python objects from the YAML content (PyYAML's default
+      full/unsafe loader supports tags like `!!python/object/apply` that
+      execute code during loading) — dangerous for ANY YAML content this
+      process didn't itself generate, not just request input. Use
+      `yaml.safe_load()` or `yaml.load(data, Loader=yaml.SafeLoader)`.
+    metadata:
+      owasp_category: "A08:2021 - Software and Data Integrity Failures"
+      cwe: "CWE-502"
+      internal_severity: HIGH
+    patterns:
+      - pattern: yaml.load(...)
+      - pattern-not: yaml.load(..., Loader=yaml.SafeLoader, ...)
+      - pattern-not: yaml.load(..., Loader=yaml.CSafeLoader, ...)
+
+  # --- XXE ----------------------------------------------------------------
+  #
+  # Scoped to lxml specifically: modern Python's stdlib XML parsers
+  # (xml.etree.ElementTree, xml.dom.minidom, xml.sax) have disabled
+  # external entity resolution by default since Python 3.7.1 — flagging
+  # them would be claiming coverage for a risk that, measured against
+  # today's Python, mostly doesn't apply. lxml's etree.XMLParser DOES
+  # resolve external entities by default, which is the real, current XXE
+  # surface worth flagging — "measure before claiming coverage" cuts both
+  # ways: don't pad with a stdlib rule that would mostly be noise either.
+
+  - id: python-xxe-lxml-parser-resolves-entities
+    languages: [python]
+    severity: ERROR
+    message: >-
+      This `lxml.etree.XMLParser` doesn't set `resolve_entities=False` —
+      lxml resolves external entities by default, so parsing any XML this
+      process didn't itself generate can be used for XXE: reading local
+      files via a crafted `<!ENTITY>` declaration, or triggering outbound
+      requests from the parsing server (a form of SSRF). Add
+      `resolve_entities=False` (and `no_network=True`/`resolve_entities=False`
+      together is the safest combination) when constructing the parser.
+    metadata:
+      owasp_category: "A05:2021 - Security Misconfiguration"
+      cwe: "CWE-611"
+      internal_severity: HIGH
+    patterns:
+      - pattern: etree.XMLParser(...)
+      - pattern-not: etree.XMLParser(..., resolve_entities=False, ...)