secrulekit 1.2.0__py3-none-any.whl

secrulekit/parsers/suricata_parser.py

@@ -0,0 +1,125 @@
+"""Suricata/Snort rule parser."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, Iterator, List, Optional
+
+
+@dataclass
+class SuricataRule:
+    action: str
+    protocol: str
+    src_addr: str
+    src_port: str
+    direction: str
+    dst_addr: str
+    dst_port: str
+    options: Dict[str, str] = field(default_factory=dict)
+    raw: str = ""
+    source_file: Optional[Path] = None
+    line_number: int = 0
+
+    @property
+    def sid(self) -> Optional[str]:
+        return self.options.get("sid")
+
+    @property
+    def msg(self) -> Optional[str]:
+        return self.options.get("msg", "").strip('"')
+
+    @property
+    def classtype(self) -> Optional[str]:
+        return self.options.get("classtype")
+
+
+class SuricataParseError(Exception):
+    def __init__(self, message: str, file: Optional[Path] = None, line: int = 0):
+        self.file = file
+        self.line = line
+        super().__init__(f"{file}:{line}: {message}" if file else message)
+
+
+# Matches the rule header: action proto src_addr src_port direction dst_addr dst_port
+_HEADER = re.compile(
+    r"^(alert|drop|pass|reject|rejectsrc|rejectdst|rejectboth)\s+"
+    r"(\w+)\s+"                    # protocol
+    r"([\w\[\]!,./]+)\s+"         # src_addr
+    r"([\w\[\]!,]+)\s+"           # src_port
+    r"(<>|->)\s+"                  # direction
+    r"([\w\[\]!,./]+)\s+"         # dst_addr
+    r"([\w\[\]!,]+)\s*"           # dst_port
+    r"\((.+)\)\s*$",               # options body
+    re.IGNORECASE,
+)
+
+# Tokenize options: key:value; or key; pairs
+_OPTION_TOKEN = re.compile(r'(\w+)\s*(?::\s*("(?:[^"\\]|\\.)*"|[^;]*))?;')
+
+
+class SuricataParser:
+    """Parse Suricata/Snort rules."""
+
+    def parse_string(
+        self, line: str, source_file: Optional[Path] = None, line_number: int = 0
+    ) -> Optional[SuricataRule]:
+        """Parse a single rule line. Returns None for comments/blank lines."""
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            return None
+
+        m = _HEADER.match(stripped)
+        if not m:
+            raise SuricataParseError("Invalid rule syntax", file=source_file, line=line_number)
+
+        opts: Dict[str, str] = {}
+        for om in _OPTION_TOKEN.finditer(m.group(8)):
+            opts[om.group(1)] = om.group(2) or ""
+
+        return SuricataRule(
+            action=m.group(1).lower(),
+            protocol=m.group(2).lower(),
+            src_addr=m.group(3),
+            src_port=m.group(4),
+            direction=m.group(5),
+            dst_addr=m.group(6),
+            dst_port=m.group(7),
+            options=opts,
+            raw=stripped,
+            source_file=source_file,
+            line_number=line_number,
+        )
+
+    def parse_file(self, path: Path | str) -> List[SuricataRule]:
+        """Parse all rules from a .rules file."""
+        path = Path(path)
+        try:
+            lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+        except OSError as e:
+            raise SuricataParseError(f"Cannot read file: {e}", file=path)
+
+        rules = []
+        for i, line in enumerate(lines, start=1):
+            rule = self.parse_string(line, source_file=path, line_number=i)
+            if rule is not None:
+                rules.append(rule)
+        return rules
+
+    def parse_directory(
+        self, directory: Path | str, recursive: bool = True
+    ) -> Iterator[SuricataRule]:
+        """Yield rules from .rules files in a directory."""
+        directory = Path(directory).resolve()
+        if not directory.is_dir():
+            raise SuricataParseError(f"Not a directory: {directory}")
+
+        glob = "**/*.rules" if recursive else "*.rules"
+        for path in sorted(directory.glob(glob)):
+            if not path.resolve().is_relative_to(directory):
+                continue
+            try:
+                yield from self.parse_file(path)
+            except SuricataParseError:
+                pass

secrulekit/parsers/yara_parser.py

@@ -0,0 +1,138 @@
+"""YARA rule parser — tokenizes and validates YARA rule syntax."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterator, List, Optional
+
+
+@dataclass
+class YaraString:
+    name: str
+    type: str  # "text", "hex", "regex"
+    value: str
+    modifiers: List[str] = field(default_factory=list)
+
+
+@dataclass
+class YaraRule:
+    name: str
+    tags: List[str] = field(default_factory=list)
+    meta: dict = field(default_factory=dict)
+    strings: List[YaraString] = field(default_factory=list)
+    condition: str = ""
+    source_file: Optional[Path] = None
+    line_number: int = 0
+
+    @property
+    def identifier(self) -> str:
+        return self.name
+
+
+_RULE_PATTERN = re.compile(
+    r"(?:private\s+|global\s+)*rule\s+(\w+)"
+    r"(?:\s*:\s*([\w\s]+?))?\s*\{(.*?)\}",
+    re.DOTALL,
+)
+_META_ITEM = re.compile(r'(\w+)\s*=\s*(?:"([^"]*?)"|(\d+)|true|false)', re.MULTILINE)
+_STRING_ITEM = re.compile(
+    r'(\$\w*)\s*=\s*(?:"((?:[^"\\]|\\.)*)"|(\{[^}]+\})|(/(?:[^/\\]|\\.)+/\w*))',
+    re.MULTILINE,
+)
+_CONDITION_BLOCK = re.compile(r"condition\s*:(.*?)(?=\}|\Z)", re.DOTALL)
+
+
+class YaraParseError(Exception):
+    def __init__(self, message: str, file: Optional[Path] = None, line: int = 0):
+        self.file = file
+        self.line = line
+        super().__init__(f"{file}:{line}: {message}" if file else message)
+
+
+class YaraParser:
+    """Parse YARA rules from files, directories, or raw strings."""
+
+    def parse_string(self, content: str, source_file: Optional[Path] = None) -> List[YaraRule]:
+        """Parse all YARA rules from a string."""
+        rules: List[YaraRule] = []
+        for match in _RULE_PATTERN.finditer(content):
+            rule = self._parse_rule_match(match, content, source_file)
+            rules.append(rule)
+        return rules
+
+    def parse_file(self, path: Path | str) -> List[YaraRule]:
+        """Parse YARA rules from a single file."""
+        path = Path(path)
+        try:
+            content = path.read_text(encoding="utf-8", errors="replace")
+        except OSError as e:
+            raise YaraParseError(f"Cannot read file: {e}", file=path)
+        rules = self.parse_string(content, source_file=path)
+        if not rules:
+            raise YaraParseError("No YARA rules found in file", file=path)
+        return rules
+
+    def parse_directory(
+        self,
+        directory: Path | str,
+        recursive: bool = True,
+        extensions: tuple[str, ...] = (".yar", ".yara"),
+    ) -> Iterator[YaraRule]:
+        """Yield YARA rules from all matching files in a directory."""
+        directory = Path(directory).resolve()
+        if not directory.is_dir():
+            raise YaraParseError(f"Not a directory: {directory}")
+
+        glob = "**/*" if recursive else "*"
+        for ext in extensions:
+            for path in sorted(directory.glob(f"{glob}{ext}")):
+                # Prevent symlink traversal outside the base directory
+                if not path.resolve().is_relative_to(directory):
+                    continue
+                try:
+                    yield from self.parse_file(path)
+                except YaraParseError:
+                    pass  # Individual file errors collected by validator
+
+    def _parse_rule_match(
+        self, match: re.Match, full_text: str, source_file: Optional[Path]
+    ) -> YaraRule:
+        name = match.group(1)
+        tags_raw = match.group(2) or ""
+        body = match.group(3)
+        line_number = full_text[: match.start()].count("\n") + 1
+
+        rule = YaraRule(
+            name=name,
+            tags=[t.strip() for t in tags_raw.split() if t.strip()],
+            source_file=source_file,
+            line_number=line_number,
+        )
+
+        # Extract meta section
+        meta_match = re.search(r"meta\s*:(.*?)(?=strings:|condition:|$)", body, re.DOTALL)
+        if meta_match:
+            for m in _META_ITEM.finditer(meta_match.group(1)):
+                rule.meta[m.group(1)] = m.group(2) or m.group(3) or ""
+
+        # Extract strings section
+        strings_match = re.search(r"strings\s*:(.*?)(?=condition:|$)", body, re.DOTALL)
+        if strings_match:
+            for s in _STRING_ITEM.finditer(strings_match.group(1)):
+                name_s = s.group(1)
+                if s.group(2) is not None:
+                    ytype, value = "text", s.group(2)
+                elif s.group(3) is not None:
+                    ytype, value = "hex", s.group(3)
+                else:
+                    ytype, value = "regex", s.group(4)
+                rule.strings.append(YaraString(name=name_s, type=ytype, value=value))
+
+        # Extract condition
+        cond = _CONDITION_BLOCK.search(body)
+        if cond:
+            rule.condition = cond.group(1).strip()
+
+        return rule

secrulekit/reporters/__init__.py

@@ -0,0 +1,4 @@
+from secrulekit.reporters.json_reporter import JsonReporter
+from secrulekit.reporters.html_reporter import HtmlReporter
+
+__all__ = ["JsonReporter", "HtmlReporter"]

secrulekit/reporters/html_reporter.py

@@ -0,0 +1,92 @@
+"""HTML audit report reporter."""
+
+from __future__ import annotations
+
+import html
+from pathlib import Path
+from typing import Optional
+
+from secrulekit.validators.rule_validator import ValidationResult, Severity
+
+
+class HtmlReporter:
+    """Generate an HTML audit report from validation results."""
+
+    def generate(self, result: ValidationResult, output: Optional[Path | str] = None) -> str:
+        rows = ""
+        for f in result.findings:
+            color = {
+                Severity.ERROR: "#dc3545",
+                Severity.WARNING: "#fd7e14",
+                Severity.INFO: "#0d6efd",
+            }.get(f.severity, "#6c757d")
+            rows += (
+                f"<tr>"
+                f"<td><span style='color:{color};font-weight:600'>{html.escape(f.severity.value.upper())}</span></td>"
+                f"<td><code>{html.escape(f.code)}</code></td>"
+                f"<td>{html.escape(f.rule_name or '')}</td>"
+                f"<td>{html.escape(f.message)}</td>"
+                f"<td style='font-size:0.85em'>{html.escape(str(f.file) if f.file else '')}:{f.line if f.line else ''}</td>"
+                f"</tr>\n"
+            )
+
+        passed_color = "#198754" if result.passed else "#dc3545"
+        passed_text = "PASSED" if result.passed else "FAILED"
+
+        page = f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>SecRuleKit Validation Report</title>
+  <style>
+    body {{ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; margin: 2rem; background: #f8f9fa; }}
+    h1 {{ color: #212529; }}
+    .badge {{ display:inline-block; padding:.3em .6em; border-radius:.4em; color:#fff; font-size:.9em; font-weight:600; }}
+    .summary {{ display:flex; gap:1.5rem; margin:1.5rem 0; flex-wrap:wrap; }}
+    .card {{ background:#fff; border-radius:.5rem; padding:1rem 1.5rem; box-shadow:0 1px 3px rgba(0,0,0,.1); min-width:120px; }}
+    .card .num {{ font-size:2rem; font-weight:700; }}
+    table {{ width:100%; border-collapse:collapse; background:#fff; border-radius:.5rem; overflow:hidden; box-shadow:0 1px 3px rgba(0,0,0,.1); }}
+    th {{ background:#343a40; color:#fff; padding:.75rem 1rem; text-align:left; }}
+    td {{ padding:.65rem 1rem; border-bottom:1px solid #dee2e6; font-size:.9em; }}
+    tr:last-child td {{ border-bottom:none; }}
+    code {{ background:#e9ecef; padding:.1em .3em; border-radius:.2em; font-size:.9em; }}
+  </style>
+</head>
+<body>
+  <h1>SecRuleKit Validation Report</h1>
+  <p>Result: <span class="badge" style="background:{passed_color}">{passed_text}</span></p>
+
+  <div class="summary">
+    <div class="card">
+      <div class="num" style="color:#198754">{result.valid_count}</div>
+      <div>Valid rules</div>
+    </div>
+    <div class="card">
+      <div class="num" style="color:#dc3545">{result.error_count}</div>
+      <div>Errors</div>
+    </div>
+    <div class="card">
+      <div class="num" style="color:#fd7e14">{result.warning_count}</div>
+      <div>Warnings</div>
+    </div>
+  </div>
+
+  <table>
+    <thead>
+      <tr><th>Severity</th><th>Code</th><th>Rule</th><th>Message</th><th>Location</th></tr>
+    </thead>
+    <tbody>
+      {rows if rows else '<tr><td colspan="5" style="text-align:center;color:#6c757d">No findings</td></tr>'}
+    </tbody>
+  </table>
+
+  <p style="margin-top:2rem;color:#6c757d;font-size:.85em">
+    Generated by <a href="https://github.com/lkop32788/SecRuleKit">SecRuleKit</a>
+  </p>
+</body>
+</html>"""
+
+        if output:
+            Path(output).write_text(page, encoding="utf-8")
+        return page

secrulekit/reporters/json_reporter.py

@@ -0,0 +1,38 @@
+"""JSON audit report reporter."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+from secrulekit.validators.rule_validator import ValidationResult
+
+
+class JsonReporter:
+    """Write validation results as a JSON report."""
+
+    def generate(self, result: ValidationResult, output: Optional[Path | str] = None) -> str:
+        data = {
+            "summary": {
+                "valid": result.valid_count,
+                "errors": result.error_count,
+                "warnings": result.warning_count,
+                "passed": result.passed,
+            },
+            "findings": [
+                {
+                    "severity": f.severity.value,
+                    "code": f.code,
+                    "message": f.message,
+                    "rule": f.rule_name,
+                    "file": str(f.file) if f.file else None,
+                    "line": f.line,
+                }
+                for f in result.findings
+            ],
+        }
+        text = json.dumps(data, indent=2, ensure_ascii=False)
+        if output:
+            Path(output).write_text(text, encoding="utf-8")
+        return text

secrulekit/utils/__init__.py

@@ -0,0 +1,3 @@
+from secrulekit.utils.helpers import fingerprint_rule, deduplicate_rules
+
+__all__ = ["fingerprint_rule", "deduplicate_rules"]

secrulekit/utils/helpers.py

@@ -0,0 +1,104 @@
+"""Utility functions: fingerprinting, deduplication, ATT&CK mapping."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from typing import Dict, Iterable, Iterator, List, Tuple, Union
+
+from secrulekit.parsers.yara_parser import YaraRule
+from secrulekit.parsers.sigma_parser import SigmaRule
+from secrulekit.parsers.suricata_parser import SuricataRule
+
+AnyRule = Union[YaraRule, SigmaRule, SuricataRule]
+
+# Minimal ATT&CK technique ID → name mapping (subset for offline use)
+_ATTACK_MAP: Dict[str, str] = {
+    "T1059": "Command and Scripting Interpreter",
+    "T1059.001": "PowerShell",
+    "T1059.003": "Windows Command Shell",
+    "T1059.004": "Unix Shell",
+    "T1055": "Process Injection",
+    "T1055.001": "Dynamic-link Library Injection",
+    "T1055.012": "Process Hollowing",
+    "T1036": "Masquerading",
+    "T1027": "Obfuscated Files or Information",
+    "T1003": "OS Credential Dumping",
+    "T1003.001": "LSASS Memory",
+    "T1082": "System Information Discovery",
+    "T1083": "File and Directory Discovery",
+    "T1071": "Application Layer Protocol",
+    "T1071.001": "Web Protocols",
+    "T1566": "Phishing",
+    "T1566.001": "Spearphishing Attachment",
+    "T1190": "Exploit Public-Facing Application",
+    "T1210": "Exploitation of Remote Services",
+    "T1021": "Remote Services",
+    "T1021.001": "Remote Desktop Protocol",
+    "T1078": "Valid Accounts",
+    "T1110": "Brute Force",
+    "T1562": "Impair Defenses",
+    "T1562.001": "Disable or Modify Tools",
+    "T1112": "Modify Registry",
+    "T1547": "Boot or Logon Autostart Execution",
+    "T1547.001": "Registry Run Keys / Startup Folder",
+}
+
+
+def fingerprint_rule(rule: AnyRule) -> str:
+    """Return a stable SHA-256 fingerprint of the rule's semantic content."""
+    if isinstance(rule, YaraRule):
+        payload = "|".join([
+            rule.name,
+            "|".join(sorted(s.value for s in rule.strings)),
+            re.sub(r"\s+", " ", rule.condition),
+        ])
+    elif isinstance(rule, SigmaRule):
+        payload = "|".join([
+            rule.title,
+            str(sorted(rule.detection.items())),
+            str(rule.logsource),
+        ])
+    else:  # Suricata
+        payload = "|".join([
+            rule.protocol,
+            rule.src_addr, rule.src_port,
+            rule.dst_addr, rule.dst_port,
+            rule.options.get("content", ""),
+            rule.options.get("sid", ""),
+        ])
+    return hashlib.sha256(payload.encode()).hexdigest()
+
+
+def deduplicate_rules(rules: Iterable[AnyRule]) -> Tuple[List[AnyRule], List[AnyRule]]:
+    """
+    Split rules into unique and duplicate lists.
+
+    Returns (unique_rules, duplicate_rules).
+    """
+    seen: Dict[str, AnyRule] = {}
+    duplicates: List[AnyRule] = []
+
+    for rule in rules:
+        fp = fingerprint_rule(rule)
+        if fp in seen:
+            duplicates.append(rule)
+        else:
+            seen[fp] = rule
+
+    return list(seen.values()), duplicates
+
+
+def lookup_attack_technique(technique_id: str) -> str:
+    """Return the ATT&CK technique name for an ID, or empty string if unknown."""
+    tid = technique_id.upper().strip()
+    return _ATTACK_MAP.get(tid, "")
+
+
+def iter_attack_tags(rule: SigmaRule) -> Iterator[Tuple[str, str]]:
+    """Yield (technique_id, technique_name) pairs from a Sigma rule's tags."""
+    for tag in rule.tags:
+        if not tag.lower().startswith("attack.t"):
+            continue
+        tid = tag.split("attack.")[-1].upper()
+        yield tid, lookup_attack_technique(tid)

secrulekit/validators/__init__.py

@@ -0,0 +1,3 @@
+from secrulekit.validators.rule_validator import RuleValidator, ValidationResult, Finding
+
+__all__ = ["RuleValidator", "ValidationResult", "Finding"]