seculens 0.3.1__py3-none-any.whl

seculens/__init__.py

@@ -0,0 +1,23 @@
+"""SecuLens Python implementation; no JavaScript runtime dependency."""
+
+from .analysis import analyze
+from .core import scan_sbom, sha256
+from .database import fetch_database, validate_database
+from .licenses import evaluate_license
+from .matcher import match_record
+from .sbom import parse_sbom
+from .word import write_word_report
+
+__version__ = "0.3.1"
+__all__ = [
+    "scan_sbom",
+    "sha256",
+    "parse_sbom",
+    "match_record",
+    "evaluate_license",
+    "fetch_database",
+    "validate_database",
+    "analyze",
+    "__version__",
+    "write_word_report",
+]

seculens/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

seculens/analysis.py

@@ -0,0 +1,211 @@
+"""Python syntax-tree review candidates and function complexity measurements."""
+
+from __future__ import annotations
+
+import ast
+import tokenize
+from pathlib import Path
+from typing import Any
+
+_IGNORED = {
+    ".git",
+    ".venv",
+    "venv",
+    "env",
+    "node_modules",
+    "vendor",
+    "dist",
+    "build",
+    "__pycache__",
+}
+_FUNCTIONS = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)
+_BRANCHES = (
+    ast.If,
+    ast.For,
+    ast.AsyncFor,
+    ast.While,
+    ast.IfExp,
+    ast.ExceptHandler,
+    ast.comprehension,
+)
+
+
+def _qualified(node: ast.AST, aliases: dict[str, str]) -> str:
+    if isinstance(node, ast.Name):
+        return aliases.get(node.id, node.id)
+    if isinstance(node, ast.Attribute):
+        parent = _qualified(node.value, aliases)
+        return f"{parent}.{node.attr}" if parent else ""
+    return ""
+
+
+def _complexity(function: ast.AST) -> tuple[int, int]:
+    complexity, deepest = 1, 0
+
+    def count(node: ast.AST, depth: int) -> None:
+        nonlocal complexity, deepest
+        if node is not function and isinstance(node, _FUNCTIONS):
+            return
+        branch = isinstance(node, _BRANCHES)
+        if branch:
+            complexity += 1
+        if isinstance(node, ast.BoolOp):
+            complexity += len(node.values) - 1
+        if isinstance(node, ast.comprehension):
+            complexity += len(node.ifs)
+        if isinstance(node, ast.match_case) and not (
+            isinstance(node.pattern, ast.MatchAs)
+            and node.pattern.pattern is None
+            and node.pattern.name is None
+        ):
+            complexity += 1
+            branch = True
+        depth += int(branch)
+        deepest = max(deepest, depth)
+        for child in ast.iter_child_nodes(node):
+            count(child, depth)
+
+    # Function defaults and decorators are outside its executed body.
+    if isinstance(function, ast.Lambda):
+        count(function.body, 0)
+    else:
+        for node in function.body:
+            count(node, 0)
+    return complexity, deepest
+
+
+def analyze(directory: str | Path) -> list[dict[str, Any]]:
+    root = Path(directory).resolve()
+    if not root.is_dir():
+        raise ValueError("Source must be a directory")
+    files: list[Path] = []
+
+    def collect(folder: Path) -> None:
+        for path in sorted(folder.iterdir()):
+            if path.is_symlink() or path.name in _IGNORED:
+                continue
+            if path.is_dir():
+                collect(path)
+            elif path.is_file() and path.suffix == ".py":
+                files.append(path)
+
+    collect(root)
+    findings: list[dict[str, Any]] = []
+    for file in files:
+        relative = file.relative_to(root).as_posix()
+        try:
+            with tokenize.open(file) as stream:
+                source = stream.read()
+            tree = ast.parse(source, filename=relative)
+        except (SyntaxError, UnicodeError, LookupError) as error:
+            findings.append(
+                {
+                    "category": "coverage",
+                    "ruleId": "PY-PARSE-ERROR",
+                    "subject": relative,
+                    "status": "unassessed",
+                    "summary": "Source could not be completely parsed",
+                    "evidence": str(error),
+                    "recommendation": "Resolve the syntax error and repeat the analysis.",
+                    "file": relative,
+                }
+            )
+            continue
+        aliases: dict[str, str] = {}
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for item in node.names:
+                    aliases[item.asname or item.name.split(".")[0]] = (
+                        item.name if item.asname else item.name.split(".")[0]
+                    )
+            elif isinstance(node, ast.ImportFrom) and node.module:
+                for item in node.names:
+                    if item.name != "*":
+                        aliases[item.asname or item.name] = f"{node.module}.{item.name}"
+
+        def add(
+            node: ast.AST,
+            category: str,
+            rule: str,
+            summary: str,
+            evidence: str | None = None,
+            *,
+            relative: str = relative,
+            source: str = source,
+        ) -> None:
+            findings.append(
+                {
+                    "category": category,
+                    "ruleId": rule,
+                    "subject": relative,
+                    "status": "review",
+                    "summary": summary,
+                    "evidence": evidence
+                    if evidence is not None
+                    else (ast.get_source_segment(source, node) or "")[:300],
+                    "recommendation": "Review the call and trace untrusted input before deciding whether it is exploitable."
+                    if category == "security"
+                    else "Consider simplifying the function and adding focused tests.",
+                    "file": relative,
+                    "line": node.lineno,
+                }
+            )
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Call):
+                name = _qualified(node.func, aliases)
+                if name in ("eval", "exec", "builtins.eval", "builtins.exec"):
+                    add(
+                        node,
+                        "security",
+                        "PY-DYNAMIC-EXECUTION",
+                        "Dynamic code execution requires review",
+                    )
+                elif name in ("os.system", "os.popen"):
+                    add(node, "security", "PY-OS-SHELL", "Shell command execution requires review")
+                elif name in {
+                    f"subprocess.{method}"
+                    for method in ("run", "Popen", "call", "check_call", "check_output")
+                } and any(
+                    k.arg == "shell" and isinstance(k.value, ast.Constant) and k.value.value is True
+                    for k in node.keywords
+                ):
+                    add(
+                        node,
+                        "security",
+                        "PY-SUBPROCESS-SHELL",
+                        "subprocess shell=True requires review",
+                    )
+                elif name in ("pickle.load", "pickle.loads"):
+                    add(
+                        node,
+                        "security",
+                        "PY-PICKLE",
+                        "Pickle deserialization requires trusted data",
+                    )
+                elif name == "yaml.load":
+                    loaders = [
+                        _qualified(k.value, aliases) for k in node.keywords if k.arg == "Loader"
+                    ]
+                    if len(node.args) > 1:
+                        loaders.append(_qualified(node.args[1], aliases))
+                    if not any(
+                        loader in ("yaml.SafeLoader", "yaml.CSafeLoader") for loader in loaders
+                    ):
+                        add(
+                            node,
+                            "security",
+                            "PY-YAML-LOAD",
+                            "YAML load without an explicit safe loader requires review",
+                        )
+            if isinstance(node, _FUNCTIONS):
+                complexity, depth = _complexity(node)
+                if complexity > 10 or depth > 4:
+                    add(
+                        node,
+                        "quality",
+                        "PY-COMPLEXITY",
+                        "Function complexity exceeds the baseline",
+                        f"cyclomatic={complexity}; nesting={depth}; thresholds=10,4",
+                    )
+    return sorted(findings, key=lambda f: (f["file"], f.get("line", 0), f["ruleId"]))

seculens/assets/OFL.txt

@@ -0,0 +1,92 @@
+This Font Software is licensed under the SIL Open Font License,
+Version 1.1.
+
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font
+creation efforts of academic and linguistic communities, and to
+provide a free and open framework in which fonts may be shared and
+improved in partnership with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply to
+any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software
+components as distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to,
+deleting, or substituting -- in part or in whole -- any of the
+components of the Original Version, by changing formats or by porting
+the Font Software to a new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed,
+modify, redistribute, and sell modified and unmodified copies of the
+Font Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components, in
+Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the
+corresponding Copyright Holder. This restriction only applies to the
+primary font name as presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created using
+the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

seculens/cli.py

@@ -0,0 +1,146 @@
+"""Native Python CLI. Syft is an optional external SBOM generator."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from .analysis import analyze
+from .core import scan_sbom, sha256
+from .database import fetch_database, validate_database
+from .sbom import parse_sbom
+from .wizard import wizard
+from .word import write_word_report
+
+
+def _json(text: str):
+    return json.loads(text)
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        return _main(argv)
+    except KeyboardInterrupt:
+        print("\nCancelled / 中止しました。", file=sys.stderr)
+        return 130
+
+
+def _main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="seculens", description="SBOM assessment and evidence-based customer reports"
+    )
+    parser.add_argument("--version", action="version", version="0.3.1")
+    commands = parser.add_subparsers(dest="command", required=True)
+    interactive = commands.add_parser("wizard", help="Interactive setup in English or Japanese")
+    interactive.add_argument("--lang", choices=("en", "ja"))
+    sbom = commands.add_parser("sbom", help="Generate CycloneDX or SPDX JSON using Syft")
+    sbom.add_argument("project", type=Path)
+    sbom.add_argument("--format", choices=("cyclonedx", "spdx"), default="cyclonedx")
+    sbom.add_argument("--syft", default="syft", help="Syft executable path")
+    sbom.add_argument("-o", "--output", required=True, type=Path)
+    scan = commands.add_parser("scan", help="Assess a JSON SBOM using OSV candidate records")
+    scan.add_argument("sbom", type=Path)
+    database = scan.add_mutually_exclusive_group(required=True)
+    database.add_argument("--db", type=Path)
+    database.add_argument(
+        "--fetch-osv", action="store_true", help="Send package names/ecosystems to OSV"
+    )
+    scan.add_argument("--policy", type=Path)
+    scan.add_argument("--source", type=Path, help="Run Python AST review rules")
+    scan.add_argument("--customer", default="Customer")
+    scan.add_argument("--target", help="Human-readable system or project name")
+    scan.add_argument("--report-style", choices=("standard", "customer"), default="standard")
+    scan.add_argument("--issuer", default="", help="Report preparer name for the customer cover")
+    scan.add_argument("--lang", choices=("en", "ja"), default="en")
+    scan.add_argument("-o", "--output", type=Path, default=Path("reports"))
+    scan.add_argument("--fail-on-findings", action="store_true")
+    args = list(sys.argv[1:] if argv is None else argv)
+    ui_language = "en"
+    if not args:
+        args, ui_language = wizard()
+        if args is None:
+            return 0
+    opts = parser.parse_args(args)
+    if opts.command == "wizard":
+        args, ui_language = wizard(opts.lang)
+        if args is None:
+            return 0
+        opts = parser.parse_args(args)
+    try:
+        if opts.command == "sbom":
+            if not opts.project.is_dir():
+                raise ValueError("Project must be a directory")
+            output_format = "cyclonedx-json" if opts.format == "cyclonedx" else "spdx-json"
+            result = subprocess.run(
+                [opts.syft, "scan", f"dir:{opts.project.resolve()}", "-o", output_format],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            parse_sbom(_json(result.stdout))
+            opts.output.parent.mkdir(parents=True, exist_ok=True)
+            opts.output.write_text(result.stdout, encoding="utf-8")
+            print(
+                f"SBOMを保存しました: {opts.output}"
+                if ui_language == "ja"
+                else f"SBOM written to {opts.output}"
+            )
+            return 0
+        # Read every input before writing output evidence, even when paths overlap.
+        input_text = opts.sbom.read_text(encoding="utf-8")
+        parsed = parse_sbom(_json(input_text))
+        if opts.db:
+            database_text = opts.db.read_text(encoding="utf-8")
+            records = validate_database(_json(database_text))
+        else:
+            print(
+                "OSVから取得中: パッケージ名とエコシステムをapi.osv.devへ送信します。"
+                if ui_language == "ja"
+                else "Fetching OSV candidates: package names and ecosystems are sent to api.osv.dev.",
+                file=sys.stderr,
+            )
+            records = fetch_database(parsed["components"])
+            database_text = json.dumps({"records": records}, ensure_ascii=False, indent=2) + "\n"
+        policy = _json(opts.policy.read_text(encoding="utf-8")) if opts.policy else {}
+        report = scan_sbom(
+            input_text,
+            records,
+            customer=opts.customer,
+            target=opts.target or opts.sbom.name,
+            policy=policy,
+            database_source=opts.db.name if opts.db else "OSV API candidate snapshot",
+            database_hash=sha256(database_text),
+        )
+        if opts.source:
+            report["findings"].extend(analyze(opts.source))
+            report["sourceAnalysis"] = {"language": "Python", "target": opts.source.resolve().name}
+        opts.output.mkdir(parents=True, exist_ok=True)
+        (opts.output / "sbom.json").write_text(input_text, encoding="utf-8")
+        (opts.output / "database.json").write_text(database_text, encoding="utf-8")
+        (opts.output / "report.json").write_text(
+            json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+        )
+        write_word_report(
+            report,
+            opts.output / "report.docx",
+            opts.lang,
+            style=opts.report_style,
+            issuer=opts.issuer,
+        )
+        print(
+            f"構成部品 {len(parsed['components'])}件、指摘 {len(report['findings'])}件。レポート: {opts.output}"
+            if ui_language == "ja"
+            else f"{len(parsed['components'])} components; {len(report['findings'])} findings. Reports: {opts.output}"
+        )
+        if opts.fail_on_findings and any(
+            f["status"] in ("affected", "denied") or f["category"] == "security"
+            for f in report["findings"]
+        ):
+            return 1
+        return 2 if any(f["status"] == "unassessed" for f in report["findings"]) else 0
+    except Exception as error:
+        print(f"SecuLens: {error}", file=sys.stderr)
+        return 2

seculens/core.py

@@ -0,0 +1,164 @@
+"""Shared report contract, assessment checks and advisory alias consolidation."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from typing import Any
+
+from .database import validate_database
+from .licenses import license_findings, validate_policy
+from .matcher import match_record, same_package, supported_version
+from .sbom import parse_sbom
+from .severity import merge_severity, record_severity
+
+LIMITATIONS = [
+    "No match means no matching record in the supplied database snapshot, not absence of vulnerabilities.",
+    "License policy checks are not a legal compliance determination.",
+    "AST rules identify review candidates and complexity, not proven exploitability.",
+    "SBOM content and package identifiers are supplied by the generating tool.",
+    "Packagist matching supports stable numeric versions and SemVer prereleases only; Composer branches and other version forms may be unassessed.",
+]
+
+
+def sha256(value: str | bytes) -> str:
+    return hashlib.sha256(value.encode("utf-8") if isinstance(value, str) else value).hexdigest()
+
+
+def scan_sbom(
+    sbom_text: str,
+    records: list[dict[str, Any]],
+    *,
+    customer: str = "Customer",
+    target: str = "SBOM",
+    policy: dict[str, Any] | None = None,
+    database_source: str = "OSV snapshot",
+    database_hash: str | None = None,
+    created_at: str | None = None,
+) -> dict[str, Any]:
+    sbom = parse_sbom(json.loads(sbom_text))
+    validate_database(records)
+    policy = validate_policy({} if policy is None else policy)
+    report: dict[str, Any] = {
+        "schemaVersion": "1.1",
+        "tool": {"name": "SecuLens", "version": "0.3.1"},
+        "createdAt": created_at
+        or datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z"),
+        "customer": customer,
+        "target": target,
+        "sbomSha256": sha256(sbom_text),
+        "database": {
+            "source": database_source,
+            "sha256": database_hash
+            or sha256(json.dumps(records, ensure_ascii=False, separators=(",", ":"))),
+        },
+        "sbom": sbom,
+        "checks": [],
+        "findings": [],
+        "limitations": list(LIMITATIONS),
+    }
+    for component in sbom["components"]:
+        report["findings"].extend(license_findings(component, policy))
+        if not supported_version(component):
+            reason = (
+                "Supported package URL required (npm, pypi or composer)"
+                if not component.get("ecosystem")
+                else "Package version is missing"
+                if not component.get("version")
+                else "Unsupported package version syntax"
+            )
+            report["checks"].append(
+                {
+                    "componentId": component["id"],
+                    "status": "unassessed",
+                    "recordsChecked": 0,
+                    "reason": reason,
+                }
+            )
+            report["findings"].append(
+                {
+                    "category": "coverage",
+                    "ruleId": "PACKAGE-IDENTITY",
+                    "subject": component["id"],
+                    "status": "unassessed",
+                    "summary": "Component could not be assessed",
+                    "evidence": reason,
+                    "recommendation": "Regenerate the SBOM with complete package URLs and versions.",
+                }
+            )
+            continue
+        candidates = [
+            r for r in records if any(same_package(component, a["package"]) for a in r["affected"])
+        ]
+        matched, uncertain = False, False
+        for record in candidates:
+            result = match_record(component, record)
+            if result == "not-affected":
+                continue
+            if result == "unknown":
+                uncertain = True
+                report["findings"].append(
+                    {
+                        "category": "coverage",
+                        "ruleId": record["id"],
+                        "subject": component["id"],
+                        "status": "unassessed",
+                        "summary": "Advisory could not be fully evaluated",
+                        "evidence": f"{component['name']}@{component['version']}; unsupported or incomplete version range",
+                        "recommendation": "Review the advisory and package version manually.",
+                    }
+                )
+                continue
+            matched = True
+            report["findings"].append(
+                {
+                    "category": "vulnerability",
+                    "ruleId": record["id"],
+                    "subject": component["id"],
+                    "status": "affected",
+                    "summary": record.get("summary") or record["id"],
+                    "evidence": f"{component['ecosystem']}:{component['name']}@{component['version']}; matched against affected versions/ranges in {record['id']}",
+                    "recommendation": "Review the advisory references for a fixed version and validate the upgrade.",
+                    "severity": record_severity(record, component),
+                    "aliases": record.get("aliases", []),
+                    "references": [ref["url"] for ref in record.get("references", [])],
+                }
+            )
+        check = {
+            "componentId": component["id"],
+            "status": "unassessed" if uncertain else "matched" if matched else "no-match",
+            "recordsChecked": len(candidates),
+        }
+        if uncertain:
+            check["reason"] = "One or more candidate records require manual review"
+        report["checks"].append(check)
+    groups: list[dict[str, Any]] = []
+    for finding in report["findings"]:
+        if finding["category"] != "vulnerability":
+            groups.append(finding)
+            continue
+        merged = dict(finding)
+        changed = True
+        while changed:
+            changed = False
+            for index in range(len(groups) - 1, -1, -1):
+                other = groups[index]
+                if other["category"] != "vulnerability" or other["subject"] != merged["subject"]:
+                    continue
+                identities = {merged["ruleId"], *merged["aliases"]}
+                if not identities.intersection({other["ruleId"], *other["aliases"]}):
+                    continue
+                all_ids = sorted(identities | {other["ruleId"], *other["aliases"]})
+                merged.update(
+                    severity=merge_severity(merged["severity"], other["severity"]),
+                    ruleId=all_ids[0],
+                    aliases=all_ids[1:],
+                    references=sorted(set(merged["references"] + other["references"])),
+                    evidence=" | ".join(sorted([merged["evidence"], other["evidence"]])),
+                )
+                groups.pop(index)
+                changed = True
+        groups.append(merged)
+    report["findings"] = sorted(groups, key=lambda f: (f["category"], f["subject"], f["ruleId"]))
+    return report