stone-sec 1.0.0__tar.gz

stone_sec-1.0.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: stone-sec
+Version: 1.0.0
+Summary: Local-first deterministic AI-enhanced security code review CLI for Python.
+Author: Your Name
+Requires-Python: >=3.11

stone_sec-1.0.0/README.md

@@ -0,0 +1,48 @@
+# Stone-Sec
+
+Local-first, CI-safe Python security scanner with optional AI explanations.
+
+## Why Stone-Sec
+- Deterministic static analysis
+- Predictable CI behavior
+- No cloud dependency
+- AI used only for explanation, never decisions
+
+## Installation
+pip install -e .
+
+## Basic Usage
+stone-sec review path/
+
+## CI Enforcement
+stone-sec review path/ --fail-on high
+
+## JSON Output
+stone-sec review path/ --format json
+
+## AI Explanations (Optional)
+stone-sec review path/ --provider ollama
+
+## GitHub Actions (CI)
+
+Run Stone-Sec automatically in GitHub Actions to enforce security checks.
+
+```yaml
+- name: Run Stone-Sec
+  uses: DaniOps/stone-sec@v1
+  with:
+    path: .
+    fail_on: high
+```
+
+## Environment Check
+stone-sec doctor
+
+## Design Philosophy
+- Detection is deterministic
+- AI is enhancement-only
+- Exit codes drive CI
+- Local-first by default
+
+## License
+MIT

stone_sec-1.0.0/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "stone-sec"
+version = "1.0.0"
+description = "Local-first deterministic AI-enhanced security code review CLI for Python."
+authors = [{ name="Your Name" }]
+requires-python = ">=3.11"
+dependencies = []
+
+[project.scripts]
+stone-sec = "stone_sec.cli:main"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"

stone_sec-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stone_sec-1.0.0/stone_sec/ai_test.py

@@ -0,0 +1,4 @@
+import os
+
+user_input = input("cmd: ")
+os.system(user_input)

stone_sec-1.0.0/stone_sec/cli.py

@@ -0,0 +1,177 @@
+from stone_sec.llm.ollama_provider import OllamaProvider
+from stone_sec.llm.prompt import build_prompt
+from stone_sec.engine.rules.runner import run_rules
+from stone_sec.engine.parser import parse_python_file
+from stone_sec.engine.rules.eval_rule import EvalUsageRule
+from stone_sec.engine.scanner import discover_python_files
+import argparse
+import sys
+from pathlib import Path
+
+
+
+def create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="stone-sec",
+        description="Local-first deterministic security code review CLI for Python."
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    # Review command
+    review_parser = subparsers.add_parser(
+        "review",
+        help="Scan Python files for security issues."
+    )
+
+    review_parser.add_argument(
+        "path",
+        type=str,
+        help="Path to Python file or directory to scan."
+    )
+
+    review_parser.add_argument(
+    "--format",
+    choices=["text", "json"],
+    default="text",
+    help="Output format (text or json)",
+)
+
+    review_parser.add_argument(
+        "--fail-on",
+        type=str,
+        choices=["low", "medium", "high", "critical"],
+        help="Fail with exit code 1 if findings meet or exceed this severity."
+    )
+
+    review_parser.add_argument(
+    "--provider",
+    choices=["ollama"],
+    help="LLM provider for enhanced explanations",
+)
+
+    # Version command
+    subparsers.add_parser(
+        "version",
+        help="Show tool version."
+    )
+
+    return parser
+
+
+def handle_review(args):
+    import sys
+    from pathlib import Path
+
+    from stone_sec.engine.severity import Severity
+    from stone_sec.engine.scanner import discover_python_files
+    from stone_sec.engine.parser import parse_python_file
+    from stone_sec.engine.rules.runner import run_rules
+    from stone_sec.llm.ollama_provider import OllamaProvider
+    from stone_sec.llm.prompt import build_prompt
+    from stone_sec.output.json_formatter import findings_to_json
+
+    target_path = Path(args.path)
+
+    if not target_path.exists():
+        print(f"[ERROR] Path does not exist: {target_path}")
+        sys.exit(1)
+
+    python_files = discover_python_files(target_path)
+
+    if not python_files:
+        if args.format == "json":
+            print(findings_to_json([]))
+        else:
+            print("No Python files found.")
+        sys.exit(0)
+
+    findings = []
+
+    # --- Deterministic detection phase ---
+    for file_path in python_files:
+        tree = parse_python_file(file_path)
+        if tree is None:
+            continue
+
+        findings.extend(run_rules(tree, file_path))
+
+    if not findings:
+        if args.format == "json":
+            print(findings_to_json([]))
+        else:
+            print("No security issues found.")
+        sys.exit(0)
+
+    # --- Optional LLM enhancement (never affects severity/exit) ---
+    provider = None
+    if getattr(args, "provider", None) == "ollama":
+        provider = OllamaProvider()
+
+    if provider:
+        for f in findings:
+            prompt = build_prompt(f)
+            result = provider.generate(prompt)
+
+            f.explanation = result.get("explanation")
+            f.exploit_scenario = result.get("exploit_scenario")
+            f.remediation = result.get("remediation")
+
+    # --- Output phase ---
+    if args.format == "json":
+        print(findings_to_json(findings))
+    else:
+        print(f"Found {len(findings)} issue(s):\n")
+
+        for f in findings:
+            print(f"[{str(f.severity)}] {f.title}")
+            print(f"Rule: {f.rule_id}")
+            print(f"File: {f.file}")
+            print(f"Line: {f.line}")
+            print(f"Snippet: {f.snippet}")
+
+            if f.explanation:
+                print(f"Explanation: {f.explanation}")
+            if f.exploit_scenario:
+                print(f"Exploit: {f.exploit_scenario}")
+            if f.remediation:
+                print(f"Fix: {f.remediation}")
+
+            print()
+
+    # --- CI fail-on logic (deterministic, unaffected by LLM/output) ---
+    highest_severity = None
+    for f in findings:
+        if highest_severity is None or f.severity.value > highest_severity.value:
+            highest_severity = f.severity
+
+    if args.fail_on:
+        threshold = Severity.from_string(args.fail_on)
+        if highest_severity and highest_severity.value >= threshold.value:
+            sys.exit(1)
+
+    sys.exit(0)
+
+
+def handle_version():
+    print("stone-sec version 0.1.0")
+    sys.exit(0)
+
+
+def main():
+    parser = create_parser()
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(0)
+
+    if args.command == "review":
+        handle_review(args)
+
+    elif args.command == "version":
+        handle_version()
+
+    else:
+        parser.print_help()
+        sys.exit(1)

stone_sec-1.0.0/stone_sec/engine/parser.py

@@ -0,0 +1,19 @@
+import ast
+from pathlib import Path
+from typing import Optional
+
+
+def parse_python_file(path: Path) -> Optional[ast.AST]:
+    """
+    Safely parse a Python file into an AST.
+
+    Returns:
+        ast.AST if parsing succeeds
+        None if file contains syntax errors or cannot be read
+    """
+    try:
+        source = path.read_text(encoding="utf-8")
+        return ast.parse(source, filename=str(path))
+    except (SyntaxError, UnicodeDecodeError, OSError):
+        # We never crash on bad files
+        return None

stone_sec-1.0.0/stone_sec/engine/rules/eval_rule.py

@@ -0,0 +1,36 @@
+import ast
+from pathlib import Path
+from typing import List
+
+from stone_sec.engine.severity import Severity
+from stone_sec.models.finding import Finding
+
+
+class EvalUsageRule(ast.NodeVisitor):
+    """
+    Detects usage of eval().
+    """
+
+    RULE_ID = "PY-EVAL-001"
+
+    def __init__(self, file_path: Path):
+        self.file_path = file_path
+        self.findings: List[Finding] = []
+
+    def visit_Call(self, node: ast.Call):
+        # Check if function name is `eval`
+        if isinstance(node.func, ast.Name) and node.func.id == "eval":
+            snippet = "eval(...)"
+
+            self.findings.append(
+                Finding(
+                    file=self.file_path,
+                    line=node.lineno,
+                    rule_id=self.RULE_ID,
+                    severity=Severity.HIGH,
+                    title="Use of eval()",
+                    snippet=snippet,
+                )
+            )
+
+        self.generic_visit(node)

stone_sec-1.0.0/stone_sec/engine/rules/os_system_rule.py

@@ -0,0 +1,39 @@
+import ast
+from pathlib import Path
+from typing import List
+
+from stone_sec.engine.severity import Severity
+from stone_sec.models.finding import Finding
+
+
+class OsSystemRule(ast.NodeVisitor):
+    """
+    Detects usage of os.system().
+    """
+
+    RULE_ID = "PY-OS-SYSTEM-001"
+
+    def __init__(self, file_path: Path):
+        self.file_path = file_path
+        self.findings: List[Finding] = []
+
+    def visit_Call(self, node: ast.Call):
+        # Detect os.system(...)
+        if (
+            isinstance(node.func, ast.Attribute)
+            and isinstance(node.func.value, ast.Name)
+            and node.func.value.id == "os"
+            and node.func.attr == "system"
+        ):
+            self.findings.append(
+                Finding(
+                    file=self.file_path,
+                    line=node.lineno,
+                    rule_id=self.RULE_ID,
+                    severity=Severity.HIGH,
+                    title="Use of os.system()",
+                    snippet="os.system(...)",
+                )
+            )
+
+        self.generic_visit(node)

stone_sec-1.0.0/stone_sec/engine/rules/runner.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+from typing import List, Type
+import ast
+
+from stone_sec.models.finding import Finding
+from stone_sec.engine.rules.eval_rule import EvalUsageRule
+from stone_sec.engine.rules.os_system_rule import OsSystemRule
+from stone_sec.engine.rules.subprocess_shell_rule import SubprocessShellRule
+
+
+RULES: List[Type[ast.NodeVisitor]] = [
+    EvalUsageRule,
+    OsSystemRule,
+    SubprocessShellRule,
+]
+
+
+def run_rules(tree: ast.AST, file_path: Path) -> List[Finding]:
+    findings: List[Finding] = []
+
+    for rule_cls in RULES:
+        rule = rule_cls(file_path)
+        rule.visit(tree)
+        findings.extend(rule.findings)
+
+    return findings

stone_sec-1.0.0/stone_sec/engine/rules/subprocess_shell_rule.py

@@ -0,0 +1,38 @@
+import ast
+from pathlib import Path
+from typing import List
+
+from stone_sec.engine.severity import Severity
+from stone_sec.models.finding import Finding
+
+
+class SubprocessShellRule(ast.NodeVisitor):
+    """
+    Detects subprocess calls with shell=True.
+    """
+
+    RULE_ID = "PY-SUBPROCESS-001"
+
+    def __init__(self, file_path: Path):
+        self.file_path = file_path
+        self.findings: List[Finding] = []
+
+    def visit_Call(self, node: ast.Call):
+        # Look for subprocess.* calls
+        if isinstance(node.func, ast.Attribute):
+            for keyword in node.keywords:
+                if keyword.arg == "shell" and isinstance(keyword.value, ast.Constant):
+                    if keyword.value.value is True:
+                        self.findings.append(
+                            Finding(
+                                file=self.file_path,
+                                line=node.lineno,
+                                rule_id=self.RULE_ID,
+                                severity=Severity.HIGH,
+                                title="subprocess call with shell=True",
+                                snippet="subprocess(..., shell=True)",
+                            )
+                        )
+                        break
+
+        self.generic_visit(node)

stone_sec-1.0.0/stone_sec/engine/scanner.py

@@ -0,0 +1,35 @@
+from pathlib import Path
+from typing import List
+
+EXCLUDED_DIRS = {
+    ".venv",
+    "venv",
+    "__pycache__",
+    "site-packages",
+}
+
+
+def discover_python_files(target: Path) -> List[Path]:
+    """
+    Discover Python files from a file or directory path,
+    excluding virtual environments and dependencies.
+    """
+
+    python_files: List[Path] = []
+
+    if target.is_file():
+        if target.suffix == ".py":
+            return [target.resolve()]
+        return []
+
+    if target.is_dir():
+        for path in target.rglob("*.py"):
+            # Skip excluded directories
+            if any(part in EXCLUDED_DIRS for part in path.parts):
+                continue
+
+            if path.is_file():
+                python_files.append(path.resolve())
+
+    python_files.sort()
+    return python_files

stone_sec-1.0.0/stone_sec/engine/severity.py

@@ -0,0 +1,18 @@
+from enum import Enum
+
+
+class Severity(Enum):
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+    CRITICAL = 4
+
+    def __str__(self) -> str:
+        return self.name.lower()
+
+    @classmethod
+    def from_string(cls, value: str) -> "Severity":
+        try:
+            return cls[value.upper()]
+        except KeyError:
+            raise ValueError(f"Invalid severity level: {value}")

stone_sec-1.0.0/stone_sec/llm/base.py

@@ -0,0 +1,14 @@
+from abc import ABC, abstractmethod
+from typing import Dict
+
+
+class LLMProvider(ABC):
+    @abstractmethod
+    def generate(self, prompt: str) -> Dict[str, str]:
+        """
+        Must return a dict with keys:
+        - explanation
+        - exploit_scenario
+        - remediation
+        """
+        raise NotImplementedError

stone_sec-1.0.0/stone_sec/llm/ollama_provider.py

@@ -0,0 +1,37 @@
+import json
+import subprocess
+from typing import Dict
+
+from stone_sec.llm.base import LLMProvider
+
+
+class OllamaProvider(LLMProvider):
+    def __init__(self, model: str = "llama3"):
+        self.model = model
+
+    def generate(self, prompt: str) -> Dict[str, str]:
+        try:
+            proc = subprocess.run(
+    ["ollama", "run", self.model],
+    input=prompt,
+    capture_output=True,
+    text=True,
+    encoding="utf-8",
+    errors="ignore",
+    timeout=120,
+)
+            output = proc.stdout.strip()
+            data = json.loads(output)
+
+            return {
+                "explanation": data.get("explanation", ""),
+                "exploit_scenario": data.get("exploit_scenario", ""),
+                "remediation": data.get("remediation", ""),
+            }
+        except Exception:
+            # Never crash — fallback
+            return {
+                "explanation": "Potential security risk detected.",
+                "exploit_scenario": "An attacker could abuse this behavior if input is controlled.",
+                "remediation": "Avoid unsafe constructs and validate inputs.",
+            }

stone_sec-1.0.0/stone_sec/llm/prompt.py

@@ -0,0 +1,27 @@
+from stone_sec.models.finding import Finding
+
+
+def build_prompt(finding: Finding) -> str:
+    """
+    Build a strict JSON-only prompt for the LLM.
+    """
+    return f"""
+You are a security analysis engine.
+
+Analyze the following security finding and return ONLY valid JSON with keys:
+- explanation
+- exploit_scenario
+- remediation
+
+Finding details:
+- Title: {finding.title}
+- Severity: {finding.severity}
+- File: {finding.file}
+- Line: {finding.line}
+- Code Snippet: {finding.snippet}
+
+Rules:
+- Do not include any text outside JSON
+- Do not change severity
+- Do not invent vulnerabilities
+"""

stone_sec-1.0.0/stone_sec/models/finding.py

@@ -0,0 +1,19 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from stone_sec.engine.severity import Severity
+
+
+@dataclass
+class Finding:
+    file: Path
+    line: int
+    rule_id: str
+    severity: Severity
+    title: str
+    snippet: str
+
+    explanation: Optional[str] = None
+    exploit_scenario: Optional[str] = None
+    remediation: Optional[str] = None

stone_sec-1.0.0/stone_sec/output/json_formatter.py

@@ -0,0 +1,30 @@
+import json
+from typing import List
+from stone_sec.models.finding import Finding
+
+
+def findings_to_json(findings: List[Finding]) -> str:
+    data = []
+
+    for f in findings:
+        data.append(
+            {
+                "rule_id": f.rule_id,
+                "severity": str(f.severity),
+                "title": f.title,
+                "file": str(f.file),
+                "line": f.line,
+                "snippet": f.snippet,
+                "explanation": f.explanation,
+                "exploit_scenario": f.exploit_scenario,
+                "remediation": f.remediation,
+            }
+        )
+
+    return json.dumps(
+        {
+            "total_findings": len(findings),
+            "findings": data,
+        },
+        indent=2,
+    )

stone_sec-1.0.0/stone_sec/test_file.py

@@ -0,0 +1,6 @@
+import os
+import subprocess
+
+os.system("ls")
+subprocess.run("ls", shell=True)
+eval("2 + 2")

stone_sec-1.0.0/stone_sec.egg-info/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: stone-sec
+Version: 1.0.0
+Summary: Local-first deterministic AI-enhanced security code review CLI for Python.
+Author: Your Name
+Requires-Python: >=3.11

stone_sec-1.0.0/stone_sec.egg-info/SOURCES.txt

@@ -0,0 +1,26 @@
+README.md
+pyproject.toml
+stone_sec/__init__.py
+stone_sec/ai_test.py
+stone_sec/cli.py
+stone_sec/test_file.py
+stone_sec.egg-info/PKG-INFO
+stone_sec.egg-info/SOURCES.txt
+stone_sec.egg-info/dependency_links.txt
+stone_sec.egg-info/entry_points.txt
+stone_sec.egg-info/top_level.txt
+stone_sec/engine/parser.py
+stone_sec/engine/scanner.py
+stone_sec/engine/severity.py
+stone_sec/engine/rules/__init__.py
+stone_sec/engine/rules/eval_rule.py
+stone_sec/engine/rules/os_system_rule.py
+stone_sec/engine/rules/runner.py
+stone_sec/engine/rules/subprocess_shell_rule.py
+stone_sec/llm/__init__.py
+stone_sec/llm/base.py
+stone_sec/llm/ollama_provider.py
+stone_sec/llm/prompt.py
+stone_sec/models/__init__.py
+stone_sec/models/finding.py
+stone_sec/output/json_formatter.py

stone_sec-1.0.0/stone_sec.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

stone_sec-1.0.0/stone_sec.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+stone-sec = stone_sec.cli:main

stone_sec-1.0.0/stone_sec.egg-info/top_level.txt

@@ -0,0 +1 @@
+stone_sec