sharelint 0.1.0__py3-none-any.whl

sharelint/__init__.py

@@ -0,0 +1,15 @@
+"""ShareLint public package API."""
+
+from ._version import __version__
+from .models import Finding, ScanLimits, ScanReport, ScanSurface, Severity
+from .scanner import scan
+
+__all__ = [
+    "Finding",
+    "ScanLimits",
+    "ScanReport",
+    "ScanSurface",
+    "Severity",
+    "__version__",
+    "scan",
+]

sharelint/__main__.py

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

sharelint/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version."""
+
+__version__ = "0.1.0"

sharelint/cli.py

@@ -0,0 +1,269 @@
+"""Command-line interface for ShareLint."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import tempfile
+from collections.abc import Sequence
+from contextlib import suppress
+from pathlib import Path
+
+from . import __version__
+from .demo import create_demo_bundle
+from .models import Severity
+from .packing import PackBlocked, PackError, pack
+from .reporters import render, render_console
+from .rules import RULES
+from .scanner import ScanInputError, scan
+
+FORMATS = ("console", "json", "sarif", "html")
+_UNSAFE_TERMINAL_CODEPOINTS = {
+    0x061C,
+    0x200E,
+    0x200F,
+    *range(0x202A, 0x202F),
+    *range(0x2066, 0x206A),
+}
+
+
+def _severity(value: str) -> Severity:
+    try:
+        return Severity.parse(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(str(exc)) from exc
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sharelint",
+        description="See what your files reveal before they leave your machine.",
+    )
+    parser.add_argument("--version", action="version", version=f"ShareLint {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    scan_parser = subparsers.add_parser("scan", help="scan a file, folder, ZIP, or OOXML package")
+    scan_parser.add_argument("target", type=Path)
+    scan_parser.add_argument("--format", choices=FORMATS, default="console")
+    scan_parser.add_argument("-o", "--output", type=Path)
+    scan_parser.add_argument("--fail-on", type=_severity, default=Severity.HIGH)
+    scan_parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="also fail when coverage is partial, skipped, or errored",
+    )
+    scan_parser.add_argument("--no-color", action="store_true")
+
+    pack_parser = subparsers.add_parser(
+        "pack", help="create a deterministic ZIP only when the policy passes"
+    )
+    pack_parser.add_argument("target", type=Path)
+    pack_parser.add_argument("-o", "--output", type=Path, required=True)
+    receipt_group = pack_parser.add_mutually_exclusive_group()
+    receipt_group.add_argument("--receipt", type=Path)
+    receipt_group.add_argument("--no-receipt", action="store_true")
+    pack_parser.add_argument(
+        "--report",
+        type=Path,
+        help="write the hash-bound JSON report here (requires --receipt)",
+    )
+    pack_parser.add_argument("--fail-on", type=_severity, default=Severity.HIGH)
+    pack_parser.add_argument("--no-color", action="store_true")
+
+    demo_parser = subparsers.add_parser("demo", help="scan a synthetic nested handoff bundle")
+    demo_parser.add_argument("-o", "--output", type=Path)
+    demo_parser.add_argument("--format", choices=FORMATS, default="console")
+    demo_parser.add_argument("--no-color", action="store_true")
+
+    subparsers.add_parser("rules", help="list stable rule identifiers")
+    explain_parser = subparsers.add_parser("explain", help="explain one rule")
+    explain_parser.add_argument("rule_id")
+    return parser
+
+
+def _validate_scan_output(target: Path, output: Path | None) -> None:
+    if output is None:
+        return
+    if output.exists() or output.is_symlink():
+        raise ScanInputError("refusing to overwrite an existing report output")
+    target_resolved = target.resolve()
+    output_resolved = output.resolve()
+    if output_resolved == target_resolved:
+        raise ScanInputError("report output must differ from the scan target")
+    if target.is_dir() and not target.is_symlink():
+        try:
+            output_resolved.relative_to(target_resolved)
+        except ValueError:
+            pass
+        else:
+            raise ScanInputError("report output must be outside the scanned directory")
+
+
+def _write_or_print(content: str, output: Path | None) -> None:
+    if output is None:
+        sys.stdout.write(content)
+        return
+    if not output.parent.is_dir():
+        raise ScanInputError("report output directory does not exist")
+    temporary: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            prefix=f".{output.name}.",
+            suffix=".tmp",
+            dir=output.parent,
+            delete=False,
+            mode="wb",
+        ) as handle:
+            temporary = Path(handle.name)
+            handle.write(content.encode("utf-8"))
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.link(temporary, output)
+    except FileExistsError as exc:
+        raise ScanInputError("refusing to overwrite an existing report output") from exc
+    except OSError as exc:
+        raise ScanInputError("report output could not be written atomically") from exc
+    finally:
+        if temporary is not None:
+            with suppress(OSError):
+                temporary.unlink(missing_ok=True)
+
+
+def _use_color(disabled: bool) -> bool:
+    return not disabled and sys.stdout.isatty() and os.environ.get("NO_COLOR") is None
+
+
+def _display_path(path: Path) -> str:
+    return "".join(
+        f"\\u{code:04x}"
+        if code < 0x20
+        or code == 0x7F
+        or 0xD800 <= code <= 0xDFFF
+        or code in _UNSAFE_TERMINAL_CODEPOINTS
+        else character
+        for character in str(path)
+        for code in (ord(character),)
+    )
+
+
+def _scan_command(arguments: argparse.Namespace) -> int:
+    _validate_scan_output(arguments.target, arguments.output)
+    report = scan(arguments.target)
+    rendered = render(
+        report,
+        arguments.format,
+        arguments.fail_on,
+        color=_use_color(arguments.no_color) and arguments.output is None,
+    )
+    _write_or_print(rendered, arguments.output)
+    blocked = report.count_at_or_above(arguments.fail_on) > 0
+    if arguments.strict and report.has_coverage_gaps:
+        blocked = True
+    return 1 if blocked else 0
+
+
+def _pack_command(arguments: argparse.Namespace) -> int:
+    if arguments.report is not None and arguments.receipt is None:
+        raise PackError("--report requires an explicit --receipt path")
+    try:
+        artifact = pack(
+            arguments.target,
+            arguments.output,
+            receipt=arguments.receipt,
+            report_output=arguments.report,
+            write_receipt=not arguments.no_receipt,
+            fail_on=arguments.fail_on,
+        )
+    except PackBlocked as exc:
+        sys.stdout.write(
+            render_console(exc.report, arguments.fail_on, color=_use_color(arguments.no_color))
+        )
+        messages = {
+            "blocking_findings": "one or more findings met the blocking threshold",
+            "coverage_incomplete": "one or more required surfaces were not fully inspected",
+            "artifact_rescan_failed": "the completed archive did not pass its rescan",
+            "source_changed": "the source changed during packing",
+        }
+        for reason in exc.reasons:
+            sys.stderr.write(f"pack blocked: {messages.get(reason, reason)}\n")
+        if exc.report_output is not None:
+            sys.stdout.write(f"Wrote {_display_path(exc.report_output)}\n")
+        if exc.receipt is not None:
+            sys.stdout.write(f"Wrote {_display_path(exc.receipt)}\n")
+        return 1
+    sys.stdout.write(
+        f"PACKED · {len(artifact.files)} file(s) · sha256:{artifact.archive_sha256}\n"
+        f"Wrote {_display_path(artifact.output)}\n"
+    )
+    if artifact.report_output is not None:
+        sys.stdout.write(f"Wrote {_display_path(artifact.report_output)}\n")
+    if artifact.receipt is not None:
+        sys.stdout.write(f"Wrote {_display_path(artifact.receipt)}\n")
+    return 0
+
+
+def _demo_command(arguments: argparse.Namespace) -> int:
+    if arguments.output is not None:
+        if arguments.output.exists() or arguments.output.is_symlink():
+            raise ScanInputError("refusing to overwrite an existing demo bundle")
+        try:
+            create_demo_bundle(arguments.output)
+        except FileExistsError as exc:
+            raise ScanInputError("refusing to overwrite an existing demo bundle") from exc
+        path = arguments.output
+        report = scan(path)
+        _write_or_print(
+            render(report, arguments.format, Severity.HIGH, color=_use_color(arguments.no_color)),
+            None,
+        )
+        return 0
+    with tempfile.TemporaryDirectory(prefix="sharelint-demo-") as directory:
+        path = create_demo_bundle(Path(directory) / "client-handoff.zip")
+        report = scan(path)
+        _write_or_print(
+            render(report, arguments.format, Severity.HIGH, color=_use_color(arguments.no_color)),
+            None,
+        )
+    return 0
+
+
+def _rules_command() -> int:
+    for rule_id in sorted(RULES):
+        rule = RULES[rule_id]
+        sys.stdout.write(f"{rule.severity.value.upper():8} {rule.rule_id:40} {rule.title}\n")
+    return 0
+
+
+def _explain_command(rule_id: str) -> int:
+    rule = RULES.get(rule_id.upper())
+    if rule is None:
+        sys.stderr.write(f"unknown rule: {rule_id}\n")
+        return 2
+    sys.stdout.write(
+        f"{rule.rule_id}\nSeverity: {rule.severity.value}\nTitle: {rule.title}\n"
+        f"Tags: {', '.join(rule.tags)}\nRemediation: {rule.remediation}\n"
+    )
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _parser()
+    arguments = parser.parse_args(argv)
+    try:
+        if arguments.command == "scan":
+            return _scan_command(arguments)
+        if arguments.command == "pack":
+            return _pack_command(arguments)
+        if arguments.command == "demo":
+            return _demo_command(arguments)
+        if arguments.command == "rules":
+            return _rules_command()
+        if arguments.command == "explain":
+            return _explain_command(arguments.rule_id)
+    except (ScanInputError, PackError, OSError) as exc:
+        message = "operating system operation failed" if isinstance(exc, OSError) else str(exc)
+        sys.stderr.write(f"sharelint: {message}\n")
+        return 2
+    parser.error("unknown command")
+    return 2

sharelint/context.py

@@ -0,0 +1,133 @@
+"""Mutable scan session state with centralized privacy and resource limits."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .models import Finding, ScanError, ScanLimits, ScanSurface, SurfaceStatus
+from .privacy import EvidenceProtector, mask_evidence
+from .rules import get_rule
+
+
+@dataclass(slots=True)
+class ScanContext:
+    limits: ScanLimits
+    protector: EvidenceProtector = field(default_factory=EvidenceProtector)
+    findings: list[Finding] = field(default_factory=list)
+    surfaces: list[ScanSurface] = field(default_factory=list)
+    errors: list[ScanError] = field(default_factory=list)
+    total_bytes: int = 0
+    archive_members: int = 0
+    finding_limit_reached: bool = False
+    _finding_keys: set[tuple[str, tuple[str, ...], str, str]] = field(default_factory=set)
+    _path_aliases: dict[str, str] = field(default_factory=dict)
+
+    def display_path(self, name: str) -> str:
+        """Redact a path while keeping colliding redactions distinguishable."""
+
+        from .scanners.path import redact_path
+
+        redacted = redact_path(name)
+        if redacted == name:
+            return redacted
+        return f"{redacted} [path-ref:{self.path_reference(name)}]"
+
+    def path_reference(self, name: str) -> str:
+        """Return a report-local opaque ordinal for a raw logical path."""
+
+        alias = self._path_aliases.get(name)
+        if alias is None:
+            alias = f"p{len(self._path_aliases) + 1:04d}"
+            self._path_aliases[name] = alias
+        return alias
+
+    def add_finding(
+        self,
+        rule_id: str,
+        source_chain: tuple[str, ...],
+        location: str,
+        evidence: str,
+        *,
+        evidence_kind: str = "generic",
+    ) -> bool:
+        if self.finding_limit_reached:
+            return False
+        if len(self.findings) >= self.limits.max_findings:
+            self.finding_limit_reached = True
+            self.errors.append(
+                ScanError(
+                    source_chain,
+                    "SL.ARCHIVE.LIMIT_EXCEEDED",
+                    "Finding count limit reached; remaining matches were not recorded",
+                )
+            )
+            self.add_surface(
+                source_chain,
+                "finding-ledger",
+                SurfaceStatus.PARTIAL,
+                0,
+                "reporting",
+                "finding count limit reached",
+            )
+            return False
+        rule = get_rule(rule_id)
+        fingerprint = self.protector.fingerprint(rule_id, evidence)
+        key = (rule_id, source_chain, location, fingerprint)
+        if key in self._finding_keys:
+            return True
+        self._finding_keys.add(key)
+        self.findings.append(
+            Finding(
+                rule_id=rule.rule_id,
+                severity=rule.severity,
+                title=rule.title,
+                source_chain=source_chain,
+                location=location,
+                masked_preview=mask_evidence(evidence, evidence_kind),
+                evidence_fingerprint=fingerprint,
+                remediation=rule.remediation,
+                tags=rule.tags,
+            )
+        )
+        return True
+
+    def add_surface(
+        self,
+        source_chain: tuple[str, ...],
+        kind: str,
+        status: SurfaceStatus,
+        bytes_inspected: int,
+        scanner: str,
+        note: str = "",
+    ) -> None:
+        self.surfaces.append(
+            ScanSurface(
+                source_chain=source_chain,
+                kind=kind,
+                status=status,
+                bytes_inspected=max(0, bytes_inspected),
+                scanner=scanner,
+                note=note,
+            )
+        )
+
+    def add_error(self, source_chain: tuple[str, ...], code: str, message: str) -> None:
+        # Parser exception strings can contain raw content. Callers provide bounded,
+        # content-free messages instead of forwarding exception text.
+        self.errors.append(ScanError(source_chain, code, message[:240]))
+
+    def consume(self, amount: int) -> bool:
+        if amount < 0 or self.total_bytes + amount > self.limits.max_total_bytes:
+            return False
+        self.total_bytes += amount
+        return True
+
+    @property
+    def remaining_bytes(self) -> int:
+        return max(0, self.limits.max_total_bytes - self.total_bytes)
+
+    def consume_member(self) -> bool:
+        if self.archive_members + 1 > self.limits.max_archive_members:
+            return False
+        self.archive_members += 1
+        return True

sharelint/demo.py

@@ -0,0 +1,98 @@
+"""A reproducible synthetic bundle used by the README and `sharelint demo`."""
+
+from __future__ import annotations
+
+import io
+import os
+import tempfile
+import zipfile
+from contextlib import suppress
+from pathlib import Path
+
+
+def _zip_bytes(files: dict[str, bytes]) -> bytes:
+    output = io.BytesIO()
+    with zipfile.ZipFile(output, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+        for name in sorted(files):
+            info = zipfile.ZipInfo(name, date_time=(1980, 1, 1, 0, 0, 0))
+            info.compress_type = zipfile.ZIP_DEFLATED
+            info.create_system = 3
+            info.external_attr = 0o100644 << 16
+            info.flag_bits |= 0x800
+            archive.writestr(info, files[name], compress_type=zipfile.ZIP_DEFLATED, compresslevel=9)
+    return output.getvalue()
+
+
+def _xlsx() -> bytes:
+    return _zip_bytes(
+        {
+            "[Content_Types].xml": b"<Types/>",
+            "xl/workbook.xml": (
+                b'<workbook xmlns="urn:demo"><sheets>'
+                b'<sheet name="Clients" state="veryHidden" sheetId="1"/>'
+                b"</sheets></workbook>"
+            ),
+            "xl/sharedStrings.xml": (
+                b'<sst xmlns="urn:demo"><si><t>AKIAIOSFODNN7EXAMPLE</t></si></sst>'
+            ),
+        }
+    )
+
+
+def _pptx() -> bytes:
+    return _zip_bytes(
+        {
+            "[Content_Types].xml": b"<Types/>",
+            "docProps/core.xml": (
+                b'<cp:coreProperties xmlns:cp="urn:cp" xmlns:dc="urn:dc">'
+                b"<dc:creator>Casey Example</dc:creator></cp:coreProperties>"
+            ),
+            "ppt/presentation.xml": b'<p:presentation xmlns:p="urn:demo"/>',
+            "ppt/slides/slide1.xml": b'<p:sld xmlns:p="urn:demo"><a:t xmlns:a="urn:a">Public demo</a:t></p:sld>',
+            "ppt/notesSlides/notesSlide1.xml": (
+                b'<p:notes xmlns:p="urn:demo" xmlns:a="urn:a">'
+                b"<a:t>Follow up with reviewer@example.test</a:t></p:notes>"
+            ),
+            "ppt/embeddings/clients.xlsx": _xlsx(),
+        }
+    )
+
+
+def create_demo_bundle(path: Path) -> Path:
+    """Atomically create a bundle containing only documented synthetic evidence."""
+
+    report = (
+        b"%PDF-1.4\n"
+        b"1 0 obj << /Author (Casey Example) /Producer (Synthetic Demo) "
+        b"/OpenAction 2 0 R >> endobj\n"
+        b"2 0 obj << /S /JavaScript /JS (app.alert('demo')) >> endobj\n"
+        b"%%EOF\n"
+    )
+    payload = _zip_bytes(
+        {
+            "README.txt": b"Synthetic ShareLint demo. No real identities or credentials.\n",
+            "deck.pptx": _pptx(),
+            "report.pdf": report,
+        }
+    )
+    if path.exists() or path.is_symlink():
+        raise FileExistsError("refusing to overwrite an existing demo bundle")
+    temporary: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            prefix=f".{path.name}.",
+            suffix=".tmp",
+            dir=path.parent,
+            delete=False,
+            mode="wb",
+        ) as handle:
+            temporary = Path(handle.name)
+            handle.write(payload)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.link(temporary, path)
+    finally:
+        if temporary is not None:
+            with suppress(OSError):
+                temporary.unlink(missing_ok=True)
+    return path

sharelint/filesystem.py

@@ -0,0 +1,58 @@
+"""Bounded filesystem enumeration shared by scanning and packing."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def bounded_directory_items(root: Path, limit: int) -> tuple[list[Path], int, bool]:
+    """Return non-directory entries without enumerating more than ``limit`` names.
+
+    The result is globally stable-sorted. Directory and metadata failures are
+    counted without forwarding platform exception text, and ``limited`` is true
+    when another entry existed beyond the configured ceiling.
+    """
+
+    result: list[Path] = []
+    pending = [root]
+    error_count = 0
+    entry_count = 0
+
+    while pending:
+        current = pending.pop()
+        current_entries: list[tuple[str, Path, bool]] = []
+        try:
+            with os.scandir(current) as entries:
+                for entry in entries:
+                    entry_count += 1
+                    if entry_count > limit:
+                        return (
+                            sorted(result, key=lambda item: item.relative_to(root).as_posix()),
+                            error_count,
+                            True,
+                        )
+                    try:
+                        is_directory = entry.is_dir(follow_symlinks=False)
+                    except OSError:
+                        error_count += 1
+                        continue
+                    current_entries.append((entry.name, Path(entry.path), is_directory))
+        except OSError:
+            error_count += 1
+            continue
+
+        current_entries.sort(key=lambda item: item[0])
+        directories: list[Path] = []
+        for _name, item, is_directory in current_entries:
+            if is_directory:
+                directories.append(item)
+            else:
+                result.append(item)
+        pending.extend(reversed(directories))
+
+    return (
+        sorted(result, key=lambda item: item.relative_to(root).as_posix()),
+        error_count,
+        False,
+    )