semhound 0.1.0__py3-none-any.whl

semhound/__init__.py

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

semhound/ai_client.py

@@ -0,0 +1,167 @@
+import json
+import re
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Optional, Tuple
+
+import yaml
+
+
+_SYSTEM_PROMPT_DEFAULT = (
+    "You are a senior application security engineer performing code review. "
+    "Evaluate whether the provided code snippet is a true positive security finding. "
+    "Be concise and precise."
+)
+
+_USER_PROMPT_TEMPLATE = """\
+Rule: {rule_message}
+
+Code snippet:
+{code_snippet}
+
+Respond in JSON only — no markdown, no explanation outside the JSON object:
+{{"confidence": <integer 0-100>, "true_positive": <true or false>, "reasoning": "<one sentence>"}}"""
+
+
+def _parse_ai_response(text: str) -> Tuple[str, str]:
+    match = re.search(r"\{.*?\}", text, re.DOTALL)
+    if not match:
+        return "ERROR", "ERROR"
+    try:
+        data = json.loads(match.group())
+        confidence = str(data.get("confidence", "ERROR"))
+        true_positive = str(data.get("true_positive", "ERROR"))
+        return confidence, true_positive
+    except (json.JSONDecodeError, KeyError):
+        return "ERROR", "ERROR"
+
+
+class BaseAIClient(ABC):
+    def __init__(self, config: dict):
+        self.model = config.get("model", "")
+        self.system_prompt = config.get("system_prompt", _SYSTEM_PROMPT_DEFAULT)
+
+    @abstractmethod
+    def analyze(self, code_snippet: str, rule_message: str) -> Tuple[str, str]:
+        """Return (confidence_score, true_positive) as strings."""
+
+    def _build_user_prompt(self, code_snippet: str, rule_message: str) -> str:
+        return _USER_PROMPT_TEMPLATE.format(
+            rule_message=rule_message,
+            code_snippet=code_snippet,
+        )
+
+
+class ClaudeClient(BaseAIClient):
+    def __init__(self, config: dict):
+        super().__init__(config)
+        try:
+            import anthropic
+        except ImportError:
+            raise ImportError(
+                "Anthropic SDK not installed. Run: pip install semhound"
+            ) from None
+        self._client = anthropic.Anthropic(api_key=config["api_key"])
+
+    def analyze(self, code_snippet: str, rule_message: str) -> tuple[str, str]:
+        response = self._client.messages.create(
+            model=self.model or "claude-sonnet-4-6",
+            max_tokens=256,
+            system=self.system_prompt,
+            messages=[{"role": "user", "content": self._build_user_prompt(code_snippet, rule_message)}],
+        )
+        return _parse_ai_response(response.content[0].text)
+
+
+class GeminiClient(BaseAIClient):
+    def __init__(self, config: dict):
+        super().__init__(config)
+        try:
+            import google.generativeai as genai
+        except ImportError:
+            raise ImportError(
+                "Google Generative AI SDK not installed. Run: pip install semhound"
+            ) from None
+        genai.configure(api_key=config["api_key"])
+        self._model = genai.GenerativeModel(
+            model_name=self.model or "gemini-1.5-pro",
+            system_instruction=self.system_prompt,
+        )
+
+    def analyze(self, code_snippet: str, rule_message: str) -> tuple[str, str]:
+        response = self._model.generate_content(self._build_user_prompt(code_snippet, rule_message))
+        return _parse_ai_response(response.text)
+
+
+class OpenAIClient(BaseAIClient):
+    def __init__(self, config: dict):
+        super().__init__(config)
+        try:
+            import openai
+        except ImportError:
+            raise ImportError(
+                "OpenAI SDK not installed. Run: pip install semhound"
+            ) from None
+        self._client = openai.OpenAI(api_key=config["api_key"])
+
+    def analyze(self, code_snippet: str, rule_message: str) -> tuple[str, str]:
+        response = self._client.chat.completions.create(
+            model=self.model or "gpt-4o",
+            max_tokens=256,
+            messages=[
+                {"role": "system", "content": self.system_prompt},
+                {"role": "user", "content": self._build_user_prompt(code_snippet, rule_message)},
+            ],
+        )
+        return _parse_ai_response(response.choices[0].message.content)
+
+
+class BedrockClient(BaseAIClient):
+    """Uses the Bedrock Converse API — model-agnostic, works with any Bedrock-hosted model."""
+
+    def __init__(self, config: dict):
+        super().__init__(config)
+        try:
+            import boto3
+        except ImportError:
+            raise ImportError(
+                "boto3 not installed. Run: pip install semhound"
+            ) from None
+        profile = config.get("aws_profile")
+        region = config.get("aws_region", "us-east-1")
+        session = boto3.Session(profile_name=profile) if profile else boto3.Session()
+        self._client = session.client("bedrock-runtime", region_name=region)
+        self._model_id = self.model or "anthropic.claude-3-5-sonnet-20241022-v2:0"
+
+    def analyze(self, code_snippet: str, rule_message: str) -> tuple[str, str]:
+        response = self._client.converse(
+            modelId=self._model_id,
+            system=[{"text": self.system_prompt}],
+            messages=[{"role": "user", "content": [{"text": self._build_user_prompt(code_snippet, rule_message)}]}],
+            inferenceConfig={"maxTokens": 256},
+        )
+        text = response["output"]["message"]["content"][0]["text"]
+        return _parse_ai_response(text)
+
+
+_PROVIDER_MAP = {
+    "claude": ClaudeClient,
+    "gemini": GeminiClient,
+    "openai": OpenAIClient,
+    "bedrock": BedrockClient,
+}
+
+
+def get_ai_client(config_path: Optional[str]) -> Optional[BaseAIClient]:
+    if config_path is None:
+        return None
+    path = Path(config_path)
+    if not path.exists():
+        raise FileNotFoundError(f"AI config not found: {config_path}")
+    with open(path) as f:
+        config = yaml.safe_load(f)
+    provider = config.get("provider", "").lower()
+    cls = _PROVIDER_MAP.get(provider)
+    if cls is None:
+        raise ValueError(f"Unknown AI provider '{provider}'. Choose from: {', '.join(_PROVIDER_MAP)}")
+    return cls(config)

semhound/cli.py

@@ -0,0 +1,139 @@
+import argparse
+import shutil
+import sys
+
+from .ai_client import get_ai_client
+from .scanner import discover_repos, download_rules, run_preflight, run_scan
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="semhound",
+        description=(
+            "Scan every repository across one or more GitHub organisations or users "
+            "using Semgrep rules."
+        ),
+    )
+    parser.add_argument(
+        "github_targets",
+        nargs="*",
+        metavar="ORG_OR_USER",
+        help=(
+            "One or more GitHub organization or username targets to scan "
+            "(e.g. my-org another-org someuser)"
+        ),
+    )
+    parser.add_argument(
+        "--orgs-file",
+        default=None,
+        metavar="PATH",
+        help=(
+            "Path to a text file listing GitHub org names to scan, one per line. "
+            "Blank lines and lines starting with '#' are ignored. "
+            "Can be combined with inline ORG_OR_USER arguments."
+        ),
+    )
+    parser.add_argument(
+        "--rules-dir",
+        default=None,
+        metavar="PATH",
+        help="Path to a local folder containing Semgrep .yaml rule files",
+    )
+    parser.add_argument(
+        "--rules-url",
+        action="append",
+        default=[],
+        metavar="URL",
+        help=(
+            "HTTPS URL of a Semgrep .yaml rule file to download before scanning. "
+            "Can be specified multiple times to download several rules."
+        ),
+    )
+    parser.add_argument(
+        "--ai-config",
+        default=None,
+        metavar="PATH",
+        help="Path to AI config file (ai.config). Omit to skip AI analysis.",
+    )
+    parser.add_argument(
+        "--threads",
+        type=int,
+        default=5,
+        metavar="N",
+        help="Number of parallel worker threads (default: 5)",
+    )
+    parser.add_argument(
+        "--sarif",
+        action="store_true",
+        default=False,
+        help="Also write a SARIF 2.1.0 report (<target>_scan.sarif) alongside the CSV",
+    )
+    args = parser.parse_args()
+
+    targets: list[str] = list(args.github_targets)
+
+    if args.orgs_file:
+        try:
+            with open(args.orgs_file, encoding="utf-8") as fh:
+                for line in fh:
+                    name = line.strip()
+                    if name and not name.startswith("#"):
+                        targets.append(name)
+        except OSError as exc:
+            parser.error(f"Cannot read --orgs-file: {exc}")
+
+    # Deduplicate while preserving order
+    seen: set[str] = set()
+    unique_targets: list[str] = []
+    for t in targets:
+        if t not in seen:
+            seen.add(t)
+            unique_targets.append(t)
+    targets = unique_targets
+
+    if not targets:
+        parser.error(
+            "At least one GitHub org or username must be provided "
+            "(inline or via --orgs-file)."
+        )
+
+    if not args.rules_dir and not args.rules_url:
+        parser.error("At least one of --rules-dir or --rules-url must be provided.")
+
+    for url in args.rules_url:
+        if not url.lower().startswith("https://"):
+            parser.error(f"--rules-url only accepts HTTPS URLs: {url}")
+
+    run_preflight()
+
+    rules_sources: list[str] = []
+    if args.rules_dir:
+        rules_sources.append(args.rules_dir)
+
+    downloaded_tmpdir: str | None = None
+    if args.rules_url:
+        try:
+            downloaded_tmpdir = download_rules(args.rules_url)
+            rules_sources.append(downloaded_tmpdir)
+        except (ValueError, RuntimeError) as exc:
+            print(f"[error] {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    try:
+        ai_client = get_ai_client(args.ai_config)
+    except (FileNotFoundError, ValueError, ImportError) as exc:
+        print(f"[error] {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    if ai_client is None:
+        print("[info] No --ai-config provided; AI analysis will be skipped.")
+
+    try:
+        for target in targets:
+            print(f"\n[info] Discovering repositories for '{target}' ...")
+            repos = discover_repos(target)
+            print(f"[info] Found {len(repos)} repository/repositories.")
+            run_scan(repos, target, rules_sources, ai_client, args.threads, output_sarif=args.sarif)
+    finally:
+        if downloaded_tmpdir:
+            shutil.rmtree(downloaded_tmpdir, ignore_errors=True)

semhound/scanner.py

@@ -0,0 +1,466 @@
+import csv
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import urllib.error
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import Optional
+
+from tqdm import tqdm
+
+from .ai_client import BaseAIClient
+
+_MAX_RETRIES = 3
+
+
+_TOOL_INSTALL = {
+    "gh": {
+        "name": "GitHub CLI",
+        "url": "https://cli.github.com",
+        "mac": "brew install gh",
+        "linux": "sudo apt install gh          # Debian/Ubuntu (apt.cli.github.com)\n"
+                 "             sudo dnf install gh          # Fedora/RHEL\n"
+                 "             See https://github.com/cli/cli/blob/trunk/docs/install_linux.md",
+        "windows": "winget install --id GitHub.cli\n"
+                   "             # or: choco install gh",
+    },
+    "git": {
+        "name": "Git",
+        "url": "https://git-scm.com",
+        "mac": "brew install git",
+        "linux": "sudo apt install git         # Debian/Ubuntu\n"
+                 "             sudo dnf install git         # Fedora/RHEL",
+        "windows": "winget install --id Git.Git\n"
+                   "             # or: choco install git  — then restart your terminal",
+    },
+    "semgrep": {
+        "name": "Semgrep",
+        "url": "https://semgrep.dev",
+        "mac": "brew install semgrep\n"
+               "             # or: pip install semgrep",
+        "linux": "pip install semgrep",
+        "windows": "pip install semgrep",
+    },
+    "ssh": {
+        "name": "OpenSSH client",
+        "url": "https://www.openssh.com",
+        "mac": "ssh ships with macOS — no install needed",
+        "linux": "sudo apt install openssh-client   # Debian/Ubuntu\n"
+                 "             sudo dnf install openssh              # Fedora/RHEL",
+        "windows": "# OpenSSH ships with Windows 10/11. If missing, run in PowerShell (Admin):\n"
+                   "             Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0",
+    },
+}
+
+
+def _print_install_hint(tool: str, system: str) -> None:
+    info = _TOOL_INSTALL.get(tool, {"name": tool, "url": "", "mac": "", "linux": "", "windows": ""})
+    if system == "Darwin":
+        cmd = info.get("mac", "")
+    elif system == "Windows":
+        cmd = info.get("windows", "")
+    else:
+        cmd = info.get("linux", "")
+    print(f"\n  {info['name']} — {info['url']}", file=sys.stderr)
+    print(f"  Install: {cmd}", file=sys.stderr)
+
+
+def run_preflight() -> None:
+    import platform
+    system = platform.system()
+
+    missing = [t for t in ("gh", "git", "semgrep", "ssh") if shutil.which(t) is None]
+    if missing:
+        print("[error] The following required tools are missing from PATH:", file=sys.stderr)
+        for tool in missing:
+            _print_install_hint(tool, system)
+        print(file=sys.stderr)
+        print("  Install the tools above, then re-run semhound.", file=sys.stderr)
+        sys.exit(1)
+
+    auth = subprocess.run(["gh", "auth", "status"], capture_output=True, text=True)
+    if auth.returncode != 0:
+        print("[error] GitHub CLI is not authenticated.", file=sys.stderr)
+        print("  Run:  gh auth login", file=sys.stderr)
+        print("  Docs: https://cli.github.com/manual/gh_auth_login", file=sys.stderr)
+        sys.exit(1)
+
+    # Warn if the token is visibly missing scopes semhound needs.
+    # Fine-grained PATs may not list scopes, so only warn when we can
+    # positively confirm scopes are present but the required ones are absent.
+    auth_output = auth.stdout + auth.stderr
+    if "Token scopes:" in auth_output:
+        missing_scopes = [s for s in ("repo", "read:org") if f"'{s}'" not in auth_output]
+        if missing_scopes:
+            print(
+                f"[warn] GitHub token may be missing scopes: {', '.join(missing_scopes)}",
+                file=sys.stderr,
+            )
+            print(
+                "  Private repos and org membership require these scopes.",
+                file=sys.stderr,
+            )
+            print(
+                f"  Re-authenticate if needed:  gh auth login --scopes {','.join(missing_scopes)}",
+                file=sys.stderr,
+            )
+
+    result = subprocess.run(
+        ["ssh", "-T", "-o", "StrictHostKeyChecking=no", "git@github.com"],
+        capture_output=True,
+        text=True,
+    )
+    combined = result.stdout + result.stderr
+    if "Hi " not in combined:
+        print("[error] GitHub SSH authentication failed.", file=sys.stderr)
+        if "Permission denied" in combined:
+            print(
+                "  Your SSH key is not registered with GitHub or does not have access.",
+                file=sys.stderr,
+            )
+            print("  Add your public key at: https://github.com/settings/keys", file=sys.stderr)
+        elif "Connection refused" in combined or "timed out" in combined.lower():
+            print(
+                "  Could not reach GitHub over SSH — port 22 may be blocked by your network.",
+                file=sys.stderr,
+            )
+            print(
+                "  Try SSH over HTTPS port 443: "
+                "https://docs.github.com/en/authentication/troubleshooting-ssh/using-ssh-over-the-https-port",
+                file=sys.stderr,
+            )
+        else:
+            print(
+                "  Ensure an SSH key is added to your GitHub account:",
+                file=sys.stderr,
+            )
+            print(
+                "  https://docs.github.com/en/authentication/connecting-to-github-with-ssh",
+                file=sys.stderr,
+            )
+        print(f"  SSH output: {combined.strip()}", file=sys.stderr)
+        sys.exit(1)
+
+
+def discover_repos(target: str) -> list[dict]:
+    result = subprocess.run(
+        ["gh", "repo", "list", target, "--limit", "1000", "--json", "sshUrl,name,defaultBranchRef"],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        err = (result.stderr or result.stdout).strip()
+        err_lower = err.lower()
+        if "could not resolve" in err_lower or "not found" in err_lower:
+            print(
+                f"[error] '{target}' was not found on GitHub. "
+                "Check the org name or username spelling.",
+                file=sys.stderr,
+            )
+        elif (
+            "must have admin rights" in err_lower
+            or "permission" in err_lower
+            or "403" in err
+            or "forbidden" in err_lower
+        ):
+            print(
+                f"[error] Permission denied when listing repositories for '{target}'.",
+                file=sys.stderr,
+            )
+            print(
+                "  Your GitHub token may be missing the 'repo' or 'read:org' scope.",
+                file=sys.stderr,
+            )
+            print(
+                "  Re-authenticate:  gh auth login --scopes repo,read:org",
+                file=sys.stderr,
+            )
+        elif "token" in err_lower and ("scope" in err_lower or "grant" in err_lower):
+            print(
+                f"[error] GitHub token lacks the required scopes to list repositories for '{target}'.",
+                file=sys.stderr,
+            )
+            print(
+                "  Re-authenticate:  gh auth login --scopes repo,read:org",
+                file=sys.stderr,
+            )
+        elif "rate limit" in err_lower or "429" in err:
+            print(
+                "[error] GitHub API rate limit exceeded. Wait a few minutes and retry.",
+                file=sys.stderr,
+            )
+        else:
+            print(
+                f"[error] Failed to list repositories for '{target}': {err}",
+                file=sys.stderr,
+            )
+        sys.exit(1)
+
+    raw = json.loads(result.stdout)
+    repos = []
+    for r in raw:
+        branch_ref = r.get("defaultBranchRef") or {}
+        repos.append({
+            "name": r["name"],
+            "sshUrl": r["sshUrl"],
+            "defaultBranch": branch_ref.get("name", "main"),
+        })
+    return repos
+
+
+def download_rules(urls: list[str]) -> str:
+    """Download semgrep rule files from HTTPS URLs into a new temp directory.
+
+    Returns the temp directory path. Caller is responsible for cleanup.
+    """
+    tmpdir = tempfile.mkdtemp(prefix="semhound_rules_")
+    for url in urls:
+        if not url.lower().startswith("https://"):
+            shutil.rmtree(tmpdir, ignore_errors=True)
+            raise ValueError(f"Only HTTPS URLs are allowed for rule downloads: {url}")
+        filename = Path(url.split("?")[0]).name or "rule.yaml"
+        dest = Path(tmpdir) / filename
+        counter = 1
+        while dest.exists():
+            dest = Path(tmpdir) / f"{dest.stem}_{counter}{dest.suffix}"
+            counter += 1
+        print(f"[info] Downloading rule: {url}")
+        try:
+            urllib.request.urlretrieve(url, dest)  # noqa: S310 – URL validated above
+        except urllib.error.URLError as exc:
+            shutil.rmtree(tmpdir, ignore_errors=True)
+            raise RuntimeError(f"Failed to download rule from {url}: {exc}") from exc
+    return tmpdir
+
+
+def _run_cmd(args: list, cwd: Optional[str] = None) -> subprocess.CompletedProcess:
+    return subprocess.run(args, capture_output=True, text=True, cwd=cwd)
+
+
+def _analyze_with_retry(
+    ai_client: BaseAIClient,
+    snippet: str,
+    message: str,
+    name: str,
+    rule_id: str,
+) -> tuple[str, str]:
+    for attempt in range(_MAX_RETRIES):
+        try:
+            confidence, true_positive = ai_client.analyze(snippet, message)
+            if confidence != "ERROR":
+                return confidence, true_positive
+            if attempt < _MAX_RETRIES - 1:
+                wait = 2 ** attempt
+                tqdm.write(f"  [retry]   {name} — {rule_id} (attempt {attempt + 1}, retrying in {wait}s)")
+                time.sleep(wait)
+        except Exception as exc:
+            if attempt < _MAX_RETRIES - 1:
+                wait = 2 ** attempt
+                tqdm.write(f"  [retry]   {name} — {rule_id} (attempt {attempt + 1}, error: {str(exc)[:60]}, retrying in {wait}s)")
+                time.sleep(wait)
+            else:
+                return "ERROR", str(exc)[:80]
+    return "ERROR", "ERROR"
+
+
+def _write_sarif(results: list[dict], output_file: str) -> None:
+    rules_seen: dict[str, str] = {}
+    for r in results:
+        rules_seen.setdefault(r["rule_id"], r["message"])
+
+    sarif = {
+        "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [{
+            "tool": {
+                "driver": {
+                    "name": "semhound",
+                    "version": "0.1.0",
+                    "rules": [
+                        {
+                            "id": rid,
+                            "shortDescription": {"text": msg[:200]},
+                            "fullDescription": {"text": msg},
+                        }
+                        for rid, msg in rules_seen.items()
+                    ],
+                }
+            },
+            "results": [
+                {
+                    "ruleId": r["rule_id"],
+                    "message": {"text": r["message"]},
+                    "locations": [{
+                        "physicalLocation": {
+                            "artifactLocation": {"uri": r["permalink"]},
+                            "region": {"startLine": r["line"]},
+                        }
+                    }],
+                    "properties": {
+                        "repository": r["repo"],
+                        "confidence": r["confidence"],
+                        "truePositive": r["true_positive"],
+                    },
+                }
+                for r in results
+            ],
+        }],
+    }
+
+    with open(output_file, "w", encoding="utf-8") as fh:
+        json.dump(sarif, fh, indent=2)
+    print(f"SARIF report written to:  {output_file}")
+
+
+def _scan_repo(
+    repo: dict,
+    org: str,
+    rules_sources: list[str],
+    ai_client: Optional[BaseAIClient],
+    csv_writer: "csv.writer",
+    csv_lock: threading.Lock,
+    sarif_results: list,
+    sarif_lock: threading.Lock,
+    progress: tqdm,
+) -> None:
+    name = repo["name"]
+    ssh_url = repo["sshUrl"]
+
+    tempdir = tempfile.mkdtemp(prefix=f"semhound_{name}_")
+    try:
+        tqdm.write(f"  [clone]   {name}")
+        clone = _run_cmd([
+            "git", "clone",
+            "--depth", "1",
+            "--single-branch",
+            "--no-tags",
+            ssh_url,
+            tempdir,
+        ])
+        if clone.returncode != 0:
+            err = clone.stderr.strip()
+            if "Permission denied (publickey)" in err:
+                tqdm.write(
+                    f"  [skip]    {name} — SSH key rejected by GitHub. "
+                    "Ensure your key has read access to this repository."
+                )
+            elif "Repository not found" in err or "Could not read from remote repository" in err:
+                tqdm.write(
+                    f"  [skip]    {name} — repository not found or your account lacks read access."
+                )
+            else:
+                tqdm.write(f"  [skip]    {name} — clone failed: {err[:200]}")
+            return
+
+        rev = _run_cmd(["git", "rev-parse", "HEAD"], cwd=tempdir)
+        commit_id = rev.stdout.strip() if rev.returncode == 0 else "HEAD"
+
+        tqdm.write(f"  [scan]    {name}")
+        semgrep_cmd = ["semgrep", "--jobs", "1"]
+        for src in rules_sources:
+            semgrep_cmd += ["--config", src]
+        semgrep_cmd += ["--json", "--quiet", tempdir]
+        semgrep = _run_cmd(semgrep_cmd)
+
+        if semgrep.returncode not in (0, 1):
+            tqdm.write(f"  [warn]    {name} — semgrep exited {semgrep.returncode}")
+
+        try:
+            raw_findings = json.loads(semgrep.stdout).get("results", [])
+        except json.JSONDecodeError:
+            tqdm.write(f"  [warn]    {name} — could not parse semgrep output")
+            raw_findings = []
+
+        sarif_batch: list[dict] = []
+
+        for finding in raw_findings:
+            rel_path = Path(finding["path"]).relative_to(tempdir)
+            line = finding["start"]["line"]
+            rule_id = finding.get("check_id", "unknown")
+            message = finding.get("extra", {}).get("message", rule_id)
+            snippet = finding.get("extra", {}).get("lines", "").strip()
+            permalink = f"https://github.com/{org}/{name}/blob/{commit_id}/{rel_path}#L{line}"
+
+            confidence, true_positive = "", ""
+            if ai_client is not None:
+                tqdm.write(f"  [analyze] {name} — {rule_id}")
+                confidence, true_positive = _analyze_with_retry(
+                    ai_client, snippet, message, name, rule_id
+                )
+                tqdm.write(
+                    f"  [ai]      {name} — {rule_id} | "
+                    f"confidence={confidence} true_positive={true_positive}"
+                )
+
+            with csv_lock:
+                csv_writer.writerow([name, rule_id, message, permalink, confidence, true_positive])
+
+            sarif_batch.append({
+                "repo": name,
+                "rule_id": rule_id,
+                "message": message,
+                "permalink": permalink,
+                "line": line,
+                "confidence": confidence,
+                "true_positive": true_positive,
+            })
+
+        with sarif_lock:
+            sarif_results.extend(sarif_batch)
+
+        tqdm.write(f"  [done]    {name} — {len(raw_findings)} finding(s)")
+
+    finally:
+        shutil.rmtree(tempdir, ignore_errors=True)
+        progress.update(1)
+
+
+def run_scan(
+    repos: list,
+    org: str,
+    rules_sources: list[str],
+    ai_client: Optional[BaseAIClient],
+    threads: int,
+    output_sarif: bool = False,
+) -> None:
+    if not repos:
+        print("[info] No repositories found for this organization.")
+        return
+
+    output_file = f"{org}_scan.csv"
+    csv_lock = threading.Lock()
+    sarif_results: list[dict] = []
+    sarif_lock = threading.Lock()
+
+    with open(output_file, "w", newline="", encoding="utf-8") as fh:
+        writer = csv.writer(fh)
+        writer.writerow([
+            "Repository", "Rule", "Issue Description", "Location",
+            "Confidence Score (AI)", "True Positive (AI)",
+        ])
+
+        progress = tqdm(total=len(repos), desc=f"Scanning {org}", unit="repo")
+        with ThreadPoolExecutor(max_workers=threads) as pool:
+            futures = {
+                pool.submit(
+                    _scan_repo, repo, org, rules_sources, ai_client,
+                    writer, csv_lock, sarif_results, sarif_lock, progress,
+                ): repo["name"]
+                for repo in repos
+            }
+            for future in as_completed(futures):
+                exc = future.exception()
+                if exc:
+                    tqdm.write(f"  [error]   {futures[future]} — {exc}")
+        progress.close()
+
+    print(f"\nResults written to:       {output_file}")
+
+    if output_sarif:
+        _write_sarif(sarif_results, f"{org}_scan.sarif")

semhound-0.1.0.dist-info/METADATA

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: semhound
+Version: 0.1.0
+Summary: Scan every repository across your GitHub organisations using Semgrep rules, with optional AI triage
+Author-email: Rohit Salecha <i@rohitsalecha.com>
+License: MIT
+Project-URL: Homepage, https://github.com/salecharohit/semhound
+Project-URL: Issues, https://github.com/salecharohit/semhound/issues
+Keywords: security,semgrep,github,appsec,threat-hunting,sast
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tqdm>=4.66
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: anthropic>=0.25
+Requires-Dist: google-generativeai>=0.5
+Requires-Dist: openai>=1.30
+Requires-Dist: boto3>=1.34
+Dynamic: license-file
+
+# semhound
+
+[![Release](https://github.com/salecharohit/semhound/actions/workflows/release.yml/badge.svg)](https://github.com/salecharohit/semhound/actions/workflows/release.yml)
+[![PyPI version](https://img.shields.io/pypi/v/semhound)](https://pypi.org/project/semhound)
+[![Python versions](https://img.shields.io/pypi/pyversions/semhound)](https://pypi.org/project/semhound)
+[![PyPI downloads](https://img.shields.io/pypi/dm/semhound)](https://pypi.org/project/semhound)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+**semhound** automates Semgrep scanning at org scale — you bring the rules, it handles discovery, cloning, scanning, and reporting across every repository in one or more GitHub organisations or user accounts. Optionally route each finding through an AI provider to triage true vs. false positives with a customised prompt.
+
+Just like [TruffleHog](https://github.com/trufflesecurity/trufflehog) sweeps repos for secrets, semhound sweeps repos for any code pattern you define.
+
+---
+
+## How it works
+
+1. **Discover** — uses `gh repo list` to find every repository for each target (org or user)
+2. **Clone** — shallow-clones each repo in parallel (`--depth 1`) via SSH
+3. **Scan** — runs your Semgrep rules across every cloned repo
+4. **Report** — writes a consolidated CSV (and optional SARIF) per target, with GitHub permalinks to every finding
+
+---
+
+## Use-cases
+
+**Bug bounty SQL injection — identify the same pattern across all repos**
+A bug bounty report flagged a SQL injection in one of your apps. Write a Semgrep rule for that pattern and sweep your entire org to find every other repo where the same issue exists.
+
+**Zero-day in a third-party OSS library — find every repo still running the vulnerable version**
+A zero-day drops for a widely-used library — think log4j. Write a Semgrep rule that matches that version string in dependency files and sweep all your orgs in one pass. You get an immediate list of every repo still running the vulnerable version so you can prioritise upgrades before the exploit is weaponised.
+
+---
+
+## Prerequisites
+
+The following tools must be installed and on your `PATH`. semhound checks for all of them at startup and prints platform-specific install instructions for anything missing.
+
+| Tool | macOS | Linux | Windows |
+|------|-------|-------|---------|
+| [GitHub CLI `gh`](https://cli.github.com) — repo discovery | `brew install gh` | [install guide](https://github.com/cli/cli/blob/trunk/docs/install_linux.md) | `winget install --id GitHub.cli` |
+| `git` — shallow cloning | `brew install git` | `sudo apt install git` | `winget install --id Git.Git` |
+| [Semgrep](https://semgrep.dev) — static analysis | `brew install semgrep` | `pip install semgrep` | `pip install semgrep` |
+| OpenSSH — cloning via SSH | ships with macOS | `sudo apt install openssh-client` | ships with Windows 10/11 |
+
+**Authenticate the GitHub CLI** (once):
+
+```bash
+gh auth login
+```
+
+**Register an SSH key** with your GitHub account (once) so semhound can clone private repos:
+[docs.github.com/en/authentication/connecting-to-github-with-ssh](https://docs.github.com/en/authentication/connecting-to-github-with-ssh)
+
+---
+
+## Installation
+
+```bash
+pip install semhound
+```
+
+**From source** (for local development):
+
+```bash
+git clone git@github.com:salecharohit/semhound.git
+cd semhound
+pip install -e .
+```
+
+---
+
+## Usage
+
+```
+semhound [ORG_OR_USER ...] [--orgs-file PATH]
+  --rules-dir PATH        Local folder of Semgrep .yaml rule files
+  --rules-url URL         HTTPS URL of a Semgrep rule file (repeatable)
+  --ai-config PATH        AI provider config file (omit to skip AI triage)
+  --threads N             Parallel worker threads per target (default: 5)
+  --sarif                 Also write a SARIF 2.1.0 report alongside the CSV
+```
+
+Pass one or more GitHub org names or usernames inline, load a list from `--orgs-file`, or mix both. All targets are deduplicated and scanned sequentially; each produces its own `<target>_scan.csv`.
+
+```bash
+# Single org
+semhound acme-corp --rules-dir ./rules
+
+# Single user account
+semhound octocat --rules-dir ./rules
+
+# Mix orgs and users inline
+semhound acme-corp octocat --rules-dir ./rules
+
+# Load orgs from a file
+semhound --orgs-file orgs.txt --rules-dir ./rules
+
+# Org file + inline username
+semhound octocat --orgs-file orgs.txt --rules-dir ./rules
+
+# Remote rule — no local files needed
+semhound acme-corp \
+  --rules-url https://raw.githubusercontent.com/example/rules/main/sqli.yaml
+
+# Full sweep: org file + remote rule + AI triage + 10 threads
+semhound --orgs-file orgs.txt \
+  --rules-dir ./rules \
+  --rules-url https://raw.githubusercontent.com/example/rules/main/extra.yaml \
+  --ai-config ai.config \
+  --threads 10
+```
+
+`orgs.txt` — one org name or username per line; blank lines and `#` comments ignored.
+
+---
+
+## Semgrep Rules
+
+Rules come from a local directory (`--rules-dir`), one or more HTTPS URLs (`--rules-url`), or both. At least one source is required. Rules must be valid Semgrep `.yaml` files. Files downloaded via `--rules-url` are placed in a temporary directory and deleted after the scan.
+
+---
+
+## AI Analysis (optional)
+
+Copy `ai.config.example` to `ai.config`, fill in your credentials, and pass `--ai-config ai.config`. Each finding is sent to the model, which returns a **confidence score** (0–100) and a **true positive** verdict. Without `--ai-config` those columns are left blank.
+
+### Supported providers
+
+| Provider | Required fields | Notes |
+|----------|----------------|-------|
+| `claude` | `api_key`, `model` | Anthropic direct API |
+| `openai` | `api_key`, `model` | OpenAI API |
+| `gemini` | `api_key`, `model` | Google Gemini API |
+| `bedrock` | `aws_region`, `model` | Uses standard AWS credential chain — no API key needed |
+
+The `system_prompt` field is optional but strongly recommended — tailoring it to your scenario produces sharper verdicts. Use the examples below as a starting point.
+
+### Example: Bug bounty SQL injection sweep — AWS Bedrock
+
+No API key needed; credentials come from `~/.aws/credentials`, an IAM role, SSO, etc. Find model IDs in the AWS Console under **Bedrock → Model access**.
+
+```yaml
+provider: bedrock
+aws_profile: default      # omit to use the default credential chain
+aws_region: us-east-1
+model: anthropic.claude-3-5-sonnet-20241022-v2:0
+
+system_prompt: >
+  You are an application security engineer triaging SQL injection findings
+  flagged by a Semgrep rule after a bug bounty report.
+  For each code snippet, assess whether user-controlled input reaches a
+  database query without going through a parameterised query or ORM.
+  Rate confidence based on how directly the input flows into the query.
+  Be concise and precise.
+```
+
+### Example: Zero-day library sweep — OpenAI
+
+```yaml
+provider: openai
+api_key: sk-...
+model: gpt-4o
+
+system_prompt: >
+  You are an application security engineer triaging findings from a
+  zero-day sweep across the org.
+  A CVE has been published for a specific function in a third-party library.
+  For each code snippet, assess whether the flagged function call matches the
+  vulnerable usage pattern described in the CVE, and whether any caller-side
+  mitigations such as input validation or version guards are already present.
+  Prioritise findings where the dangerous call is reachable with no mitigations.
+  Be concise and precise.
+```
+
+**Live triage output:**
+
+```
+[analyze] my-repo — sqli-raw-format
+[ai]      my-repo — sqli-raw-format | confidence=91 true_positive=true
+```
+
+If a provider returns an unparseable response, the tool retries up to 3 times with exponential backoff (1 s → 2 s → 4 s) before recording `ERROR`.
+
+---
+
+## Output
+
+Results are written to `<target>_scan.csv`. Pass `--sarif` to also produce `<target>_scan.sarif`.
+
+| Column | Description |
+|--------|-------------|
+| Repository | Repository name |
+| Rule | Semgrep rule ID |
+| Issue Description | Rule message |
+| Location | GitHub permalink to the exact line |
+| Confidence Score (AI) | 0–100 (blank without `--ai-config`) |
+| True Positive (AI) | `true` / `false` (blank without `--ai-config`) |
+
+---
+
+## FAQ
+
+**Who is this tool for?**
+semhound is built for **Purple and Blue teams** — security engineers who need to identify vulnerable code patterns at org scale, not one repo at a time. Whether you're responding to a bug bounty report, sweeping for a CVE across an acquired company's codebase, or enforcing a security pattern across 200 repos, semhound gives you the answer in one command.
+
+**What authentication is needed?**
+semhound uses two mechanisms. `gh auth login` creates an OAuth token used for repository discovery via `gh repo list`. Cloning uses SSH with a key registered in your GitHub account — preferred over HTTPS because keys don't expire, are never embedded in URLs, and have no credential helper overhead when cloning hundreds of repos in parallel.
+
+**Does it scan git history?**
+No. semhound does a shallow clone of the default branch (`--depth 1`) and scans the current state of the code. It is designed for broad, fast coverage across many repos, not deep forensic history analysis.
+
+**How is this different from TruffleHog or Gitleaks?**
+TruffleHog and Gitleaks are purpose-built secrets scanners — they detect API keys, tokens, and credentials using their own built-in signatures. semhound is not a secrets scanner. It runs any Semgrep rule you give it — security vulnerabilities, dangerous function calls, vulnerable dependency versions, custom code patterns. Use TruffleHog for secrets; use semhound when you need to hunt for arbitrary code patterns at org scale.
+
+**How is this different from running Semgrep directly?**
+Semgrep is a scanner; it needs a target. Running it directly means you clone each repo yourself, run the command, collect results, repeat. semhound wraps that entire loop — it discovers every repo in an org or user account, clones them in parallel, runs your rules across all of them, and writes a consolidated CSV. One command replaces what would otherwise be a shell script across dozens or hundreds of repos.
+
+**How is this different from GitHub Advanced Security (GHAS)?**
+GHAS must be enabled repository by repository and requires a GitHub Enterprise licence for private repos. semhound works with any GitHub account, needs no per-repo setup, and lets you bring your own Semgrep rules. It runs on demand from anywhere, against any org or user you have access to.
+
+**How is this different from git-secrets?**
+git-secrets is a pre-commit hook that stops developers from committing secrets at commit time. semhound is a retrospective org-wide scanner — it sweeps repositories that already exist, across teams and orgs, looking for patterns you define. Different problem, different tool.

semhound-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+semhound/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+semhound/ai_client.py,sha256=Tax77vJWEAaCJuONKAIX7gVQ9dHvrWC46NlEcSu0P-A,5980
+semhound/cli.py,sha256=sa0zPH5aotLdvzWdPy_1K5S3STKXKqrbylC0BEDE47I,4349
+semhound/scanner.py,sha256=-lMFpjq1idw8dOmcRUaHaK5qDOiZMme3KWOSun6fA-A,17113
+semhound-0.1.0.dist-info/licenses/LICENSE,sha256=rFlLsEXWg6OiR87ZpTTpbfrnDONkPDo4xfO2RLtFJ0I,1070
+semhound-0.1.0.dist-info/METADATA,sha256=t36kR4EHHm_mceCz3_YWQk9iGCZ-NJRaDQzem694-0k,12142
+semhound-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+semhound-0.1.0.dist-info/entry_points.txt,sha256=4z61JRy6aNlmbI8lUSAnUVUopYayblJVC6BCmrlQzQg,47
+semhound-0.1.0.dist-info/top_level.txt,sha256=-jRzGRa_6b3W3moaNb6RxvSJzJ4JZHKATOKcyxc5C0E,9
+semhound-0.1.0.dist-info/RECORD,,

semhound-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

semhound-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+semhound = semhound.cli:main

semhound-0.1.0.dist-info/licenses/LICENSE

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

semhound-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+semhound