first commit

Author: programmersd21

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: programmersd21s

.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.benchmarks/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/

LICENSE.md

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 programmersd21
+
+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.
+
+Contact: geniussantu1983@gmail.com

README.md

@@ -0,0 +1,120 @@
+<div align="center">
+
+# aur_checker
+
+A CLI tool to inspect Arch Linux AUR PKGBUILD files for security risks using static analysis and AI.
+
+<p align="center">
+  <img src="https://img.shields.io/github/actions/workflow/status/programmersd21/aur_checker/ci.yml?style=for-the-badge" alt="Build Status">
+  <img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge" alt="License Badge">
+  <img src="https://img.shields.io/badge/Python-3.10+-blue?style=for-the-badge&logo=python" alt="Python Version">
+</p>
+
+> **Support this project** - [Sponsor](https://github.com/sponsors/programmersd21) or star the repo.
+
+---
+
+## Pipeline
+
+```
+PKGBUILD → FETCH → STATIC_ANALYSIS → METADATA → SCORING → AI (70% weight) → VERDICT
+```
+
+1. **Fetch** - Downloads PKGBUILD from AUR CGit.
+2. **Static analysis** - Regex scan for remote execution, obfuscation, system modification, package manager calls.
+3. **Metadata** - AUR RPC v5 info (maintainer, orphan status, age).
+4. **Scoring** - Aggregates signals into a 0-100 risk score.
+5. **AI** - `gemini-3.1-flash-lite` via `google-genai`. Blended 30/70 (static/AI) for the final verdict.
+6. **Output** - Rich terminal output or JSON.
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/programmersd21/aur_checker.git
+cd aur_checker
+pip install -e .
+```
+
+---
+
+## AI Configuration
+
+AI runs automatically. Set your API key:
+
+| Platform | Command |
+|----------|---------|
+| Linux/macOS | `export AURCHECKER_AI_API_KEY="your-key"` |
+| Windows PowerShell | `$env:AURCHECKER_AI_API_KEY="your-key"` |
+
+Optional overrides:
+- `AURCHECKER_AI_MODEL` - model name (default: `gemini-3.1-flash-lite`)
+- `AURCHECKER_AI_TIMEOUT` - timeout in ms (default: `120000`)
+
+---
+
+## Usage
+
+```bash
+# Check a single package
+aur_checker check keepassx2
+
+# JSON output
+aur_checker --json check keepassx2
+
+# Check multiple packages
+aur_checker batch keepassx2 visual-studio-code-bin
+aur_checker batch --file packages.txt
+
+# AI analysis from saved JSON
+aur_checker explain --input analysis.json
+
+# Check + install (makepkg required)
+aur_checker install keepassx2
+
+# Clear cached results
+aur_checker clear-cache
+```
+
+---
+
+## Scoring
+
+| Score | Level | Verdict |
+|-------|-------|---------|
+| 0-20 | LOW | ALLOW |
+| 21-50 | MEDIUM | REVIEW |
+| 51-100 | HIGH | DENY |
+
+Signals detected by static analysis:
+
+| Signal | Trigger | Max weight |
+|--------|---------|-----------|
+| remote_exec | curl/wget piped to shell | 50 |
+| external_calls | Non-source HTTPS URLs | 15 |
+| pkg_manager | npm/pip/cargo/go/gem/pacman/yay | 10 |
+| orphan_adopted | Package without maintainer | 10 |
+| obfuscation | base64, hex, printf+xxd, openssl, eval | 30 |
+| system_mod | Writing to /etc, /usr/lib, /opt, /boot | 30 |
+| maintainer_changed | Maintainer turnover (always UNKNOWN) | 0 |
+
+---
+
+## Quality Assurance
+
+```bash
+pytest
+mypy .
+ruff check .
+```
+
+---
+
+## License
+
+MIT. See [LICENSE.md](LICENSE.md).
+
+Contact: [geniussantu1983@gmail.com](mailto:geniussantu1983@gmail.com)
+
+</div>

__main__.py

@@ -0,0 +1,4 @@
+from cli.root import app
+
+if __name__ == "__main__":
+    app()

ai/__init__.py

@@ -0,0 +1 @@
+# Empty init file for ai package

ai/client.py

@@ -0,0 +1,138 @@
+import json
+import os
+from concurrent.futures import ThreadPoolExecutor, TimeoutError as FuturesTimeout
+from typing import Any
+from google import genai
+from google.genai import types
+from core.context import PipelineContext, AIOutput, ErrorDetail
+from ai.contract import AIOutputContract
+
+
+def _call_gemini(
+    api_key: str,
+    model_name: str,
+    prompt: str,
+    timeout_ms: int,
+) -> dict[str, Any]:
+    client = genai.Client(
+        api_key=api_key,
+        http_options=types.HttpOptions(timeout=timeout_ms),
+    )
+
+    contents = [
+        types.Content(
+            role="user",
+            parts=[
+                types.Part.from_text(text=prompt),
+            ],
+        ),
+    ]
+
+    gen_config = types.GenerateContentConfig()
+
+    response = client.models.generate_content(
+        model=model_name,
+        contents=contents,  # type: ignore[arg-type]
+        config=gen_config,
+    )
+
+    text = ""
+    if response.text:
+        text = response.text.strip()
+
+    if not text:
+        raise ValueError("AI returned an empty response.")
+
+    result: dict[str, Any] = json.loads(text)
+    return result
+
+
+def analyze_with_gemini(ctx: PipelineContext) -> PipelineContext:
+    api_key = os.getenv("AURCHECKER_AI_API_KEY")
+    if not api_key:
+        ctx.errors.append(
+            ErrorDetail(
+                code="AI_DISABLED", stage="AI", message="AURCHECKER_AI_API_KEY env var is not set.", recoverable=True
+            )
+        )
+        return ctx
+
+    if not ctx.features or not ctx.metadata:
+        ctx.errors.append(
+            ErrorDetail(
+                code="AI_SCHEMA_INVALID",
+                stage="AI",
+                message="Cannot run AI analysis without features and metadata.",
+                recoverable=True,
+            )
+        )
+        return ctx
+
+    payload = {
+        "package": ctx.package,
+        "features": ctx.features.dict(),
+        "metadata": ctx.metadata.dict(),
+        "risk_score": ctx.risk_score,
+        "risk_level": ctx.risk_level,
+    }
+    payload_str = json.dumps(payload)
+
+    model_name = os.getenv("AURCHECKER_AI_MODEL", "gemini-3.1-flash-lite")
+    timeout_ms = int(os.getenv("AURCHECKER_AI_TIMEOUT", "120000"))
+    deadline_s = timeout_ms / 1000 + 5
+
+    prompt = f"""You are a security expert analyzing an Arch AUR PKGBUILD. Output ONLY valid JSON matching this schema exactly:
+{{
+  "summary": "string (max 200 chars) - brief risk overview",
+  "suspicious_patterns": ["string"] - list of specific dangerous patterns found (max 5)",
+  "attack_surface": "string (max 300 chars) - what an attacker could exploit",
+  "rationale": ["string"] - reasons for the risk score (max 3)",
+  "ai_risk_score": integer 0-100 - your independent risk score based on PKGBUILD content",
+  "ai_risk_level": "LOW" or "MEDIUM" or "HIGH",
+  "ai_risk_details": "string (max 500 chars) - what specifically contributed to the risk score"
+}}
+
+Input: {payload_str}
+
+Output valid JSON only. No markdown. No prose."""
+
+    try:
+        with ThreadPoolExecutor(max_workers=1) as pool:
+            fut = pool.submit(_call_gemini, api_key, model_name, prompt, timeout_ms)
+            result = fut.result(timeout=deadline_s)
+
+        validated = AIOutputContract(**result)
+
+        ctx.ai_analysis = AIOutput(
+            summary=validated.summary,
+            suspicious_patterns=validated.suspicious_patterns,
+            attack_surface=validated.attack_surface,
+            rationale=validated.rationale,
+            ai_risk_score=validated.ai_risk_score,
+            ai_risk_level=validated.ai_risk_level,
+            ai_risk_details=validated.ai_risk_details,
+        )
+    except FuturesTimeout:
+        ctx.errors.append(
+            ErrorDetail(
+                code="AI_TIMEOUT",
+                stage="AI",
+                message=f"AI did not respond within {int(deadline_s)}s.",
+                recoverable=True,
+            )
+        )
+    except json.JSONDecodeError as e:
+        ctx.errors.append(
+            ErrorDetail(code="AI_SCHEMA_INVALID", stage="AI", message=f"JSON Decode Error: {str(e)}", recoverable=True)
+        )
+    except Exception as e:
+        ctx.errors.append(
+            ErrorDetail(
+                code="AI_TIMEOUT" if "timeout" in str(e).lower() else "AI_SCHEMA_INVALID",
+                stage="AI",
+                message=str(e),
+                recoverable=True,
+            )
+        )
+
+    return ctx

ai/contract.py

@@ -0,0 +1,45 @@
+from pydantic import BaseModel, field_validator, Field
+from typing import List
+
+
+class AIOutputContract(BaseModel):
+    summary: str
+    suspicious_patterns: List[str]
+    attack_surface: str
+    rationale: List[str]
+    ai_risk_score: int = Field(default=0, ge=0, le=100)
+    ai_risk_level: str = Field(default="LOW")
+    ai_risk_details: str = ""
+
+    @field_validator("summary")
+    @classmethod
+    def validate_summary(cls, v):
+        return str(v)[:200]
+
+    @field_validator("suspicious_patterns")
+    @classmethod
+    def validate_patterns(cls, v):
+        return [str(p) for p in v][:5]
+
+    @field_validator("attack_surface")
+    @classmethod
+    def validate_attack_surface(cls, v):
+        return str(v)[:300]
+
+    @field_validator("rationale")
+    @classmethod
+    def validate_rationale(cls, v):
+        return [str(r) for r in v][:3]
+
+    @field_validator("ai_risk_level")
+    @classmethod
+    def validate_risk_level(cls, v):
+        v = str(v).upper()
+        if v not in ("LOW", "MEDIUM", "HIGH"):
+            return "LOW"
+        return v
+
+    @field_validator("ai_risk_details")
+    @classmethod
+    def validate_risk_details(cls, v):
+        return str(v)[:500]

cache/__init__.py

@@ -0,0 +1 @@
+# Empty init file for cache package