startup-sbom 2.0.0__py3-none-any.whl

startup_sbom/__init__.py

@@ -0,0 +1,45 @@
+"""startup-sbom: what runs at boot, what it is made of, and how it can be attacked.
+
+Library use::
+
+    from startup_sbom import ScanOptions, scan
+
+    report = scan("oci-dir:./image", ScanOptions(offline=True))
+    for threat in report.threats:
+        print(threat.ssvc.decision if threat.ssvc else "-", threat.title)
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING, Any
+
+try:
+    __version__ = version("startup-sbom")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0+unknown"
+
+if TYPE_CHECKING:
+    from startup_sbom.context import ScanOptions
+    from startup_sbom.models import Report
+
+__all__ = ["Report", "ScanOptions", "__version__", "scan"]
+
+
+def scan(target: str, options: ScanOptions | None = None, **kwargs: Any) -> Report:
+    """Analyse ``target`` (see :func:`startup_sbom.pipeline.scan`)."""
+    from startup_sbom.pipeline import scan as _scan
+
+    return _scan(target, options, **kwargs)
+
+
+def __getattr__(name: str) -> Any:
+    if name == "ScanOptions":
+        from startup_sbom.context import ScanOptions
+
+        return ScanOptions
+    if name == "Report":
+        from startup_sbom.models import Report
+
+        return Report
+    raise AttributeError(name)

startup_sbom/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m startup_sbom``."""
+
+from startup_sbom.cli import main
+
+if __name__ == "__main__":
+    main()

startup_sbom/ai/__init__.py

@@ -0,0 +1,84 @@
+"""Agentic AI analysis over a finished scan report (optional ``ai`` extra).
+
+The deterministic report stays the source of truth.  Agents only *read* it through
+paged, size-capped, spotlighted tools, every output is machine-checked against the
+report ids and numbers (:mod:`startup_sbom.ai.grounding`), and the result is an
+:class:`~startup_sbom.models.AIAssessment` stored in ``report.ai``::
+
+    from startup_sbom.ai import analyze
+
+    report.ai = analyze(report, profile="cheap", max_cost_usd=0.50)
+
+Importing this package is cheap: ``pydantic_ai``, ``mcp`` and ``fasta2a`` are only
+imported by the submodules that need them, with a friendly error when the extra
+is missing.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+from startup_sbom.errors import StartupSBOMError
+
+if TYPE_CHECKING:
+    from startup_sbom.ai.orchestrator import analyze, analyze_async
+    from startup_sbom.ai.outputs import render_assessment
+    from startup_sbom.ai.providers import available_providers
+
+__all__ = [
+    "AIBudgetError",
+    "AIConfigError",
+    "AIError",
+    "AIUnavailableError",
+    "analyze",
+    "analyze_async",
+    "available_providers",
+    "render_assessment",
+    "require",
+]
+
+INSTALL_HINT = "pip install 'startup-sbom[ai]'"
+SERVER_INSTALL_HINT = "pip install 'startup-sbom[agents-server]'"
+
+
+class AIError(StartupSBOMError):
+    """Base class for errors raised by the AI layer."""
+
+
+class AIUnavailableError(AIError):
+    """An optional dependency of the AI layer is not installed."""
+
+
+class AIConfigError(AIError):
+    """Provider, model, agent or server configuration is invalid."""
+
+
+class AIBudgetError(AIError):
+    """A run hit its usage limits or its ``max_cost_usd`` guard."""
+
+
+def require(module: str, *, hint: str = INSTALL_HINT) -> Any:
+    """Import ``module`` or raise :class:`AIUnavailableError` naming the extra to install."""
+    try:
+        return importlib.import_module(module)
+    except ImportError as exc:
+        raise AIUnavailableError(
+            f"the AI features need the optional dependency "
+            f"{module.split('.', maxsplit=1)[0]!r}: {hint}"
+        ) from exc
+
+
+_LAZY = {
+    "analyze": "startup_sbom.ai.orchestrator",
+    "analyze_async": "startup_sbom.ai.orchestrator",
+    "render_assessment": "startup_sbom.ai.outputs",
+    "available_providers": "startup_sbom.ai.providers",
+}
+
+
+def __getattr__(name: str) -> Any:
+    module = _LAZY.get(name)
+    if module is None:
+        raise AttributeError(name)
+    return getattr(importlib.import_module(module), name)

startup_sbom/ai/a2a.py

@@ -0,0 +1,208 @@
+"""Serve the orchestrator and specialists over A2A 1.0 with ``fasta2a``.
+
+Pydantic AI 2 removed ``Agent.to_a2a()``; the replacement is building ``FastA2A``
+around ``fasta2a.pydantic_ai.AgentWorker``, with two fixes verified against the
+official ``a2a-sdk`` client:
+
+1. **deps**: the worker calls ``agent.run(message_history=...)`` without deps, so the
+   lifespan binds them with ``agent.override(deps=...)`` (contextvars propagate into
+   the worker's task group).
+2. **timestamps**: fasta2a 2.1.1 writes naive timestamps the a2a-sdk (protobuf JSON)
+   rejects; :class:`UTCStorage` rewrites them as UTC ``...Z``.
+
+The orchestrator card is served at the root; each local specialist gets its own card
+under ``/agents/<name>``.  Binds 127.0.0.1 by default; a bearer token
+(``STARTUP_SBOM_AGENT_TOKEN``) is required on any other interface.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Sequence
+from contextlib import AsyncExitStack, ExitStack, asynccontextmanager
+from datetime import UTC, datetime
+from typing import Any
+
+from startup_sbom.ai import SERVER_INSTALL_HINT, AIUnavailableError
+from startup_sbom.ai.acp import TokenAuthMiddleware
+from startup_sbom.ai.index import ReportIndex
+from startup_sbom.ai.orchestrator import ModelSet, build_orchestrator
+from startup_sbom.ai.registry import AgentRegistry, AgentSpec
+from startup_sbom.ai.tools import AgentDeps, report_toolset
+from startup_sbom.models import Report
+
+try:
+    from fasta2a import FastA2A
+    from fasta2a.broker import InMemoryBroker
+    from fasta2a.pydantic_ai import AgentWorker
+    from fasta2a.schema import AgentProvider, Artifact, Message, Skill, Task, TaskState
+    from fasta2a.storage import InMemoryStorage
+    from pydantic_ai import Agent
+    from starlette.applications import Starlette
+    from starlette.routing import BaseRoute, Mount
+    from starlette.types import ASGIApp
+except ImportError as exc:  # pragma: no cover - exercised only without the extra
+    raise AIUnavailableError(f"the A2A server needs 'fasta2a': {SERVER_INSTALL_HINT}") from exc
+
+PROVIDER = AgentProvider(
+    organization="startup-sbom", url="https://github.com/morpheuslord/Startup-SBOM"
+)
+
+
+class UTCStorage(InMemoryStorage):  # type: ignore[misc] # fasta2a ships no types
+    """``InMemoryStorage`` whose task timestamps are UTC with a ``Z`` suffix.
+
+    fasta2a 2.1.1 writes ``datetime.now().isoformat()`` (naive, no zone); the official
+    a2a-sdk client fails to parse that protobuf timestamp.  Worth fixing upstream.
+    """
+
+    @staticmethod
+    def _utc(task: Task) -> Task:
+        status = task.get("status")
+        if status is not None:
+            status["timestamp"] = datetime.now(UTC).isoformat().replace("+00:00", "Z")
+        return task
+
+    async def submit_task(self, context_id: str, message: Message) -> Task:
+        return self._utc(await super().submit_task(context_id, message))
+
+    async def update_task(
+        self,
+        task_id: str,
+        state: TaskState,
+        new_artifacts: list[Artifact] | None = None,
+        new_messages: list[Message] | None = None,
+    ) -> Task:
+        return self._utc(await super().update_task(task_id, state, new_artifacts, new_messages))
+
+
+def agent_app(
+    agent: Agent[AgentDeps, Any],
+    deps: AgentDeps,
+    *,
+    name: str,
+    description: str,
+    url: str,
+    skills: list[Skill],
+    version: str,
+    extra_toolsets: bool = True,
+) -> FastA2A:
+    """One A2A app (card + JSON-RPC) around ``agent`` with deps bound in the lifespan."""
+    storage, broker = UTCStorage(), InMemoryBroker()
+    worker = AgentWorker(agent=agent, broker=broker, storage=storage)
+
+    @asynccontextmanager
+    async def lifespan(app: FastA2A) -> AsyncIterator[None]:
+        async with AsyncExitStack() as stack:
+            await stack.enter_async_context(app.task_manager)
+            await stack.enter_async_context(agent)
+            overrides = ExitStack()
+            stack.enter_context(overrides)
+            if extra_toolsets:
+                overrides.enter_context(agent.override(deps=deps, toolsets=[report_toolset()]))
+            else:
+                overrides.enter_context(agent.override(deps=deps))
+            await stack.enter_async_context(worker.run())
+            yield
+
+    return FastA2A(
+        storage=storage,
+        broker=broker,
+        name=name,
+        url=url,
+        version=version,
+        description=description,
+        provider=PROVIDER,
+        skills=skills,
+        default_input_modes=["text/plain"],
+        default_output_modes=["application/json"],
+        lifespan=lifespan,
+    )
+
+
+def _skill(spec: AgentSpec) -> Skill:
+    return Skill(
+        id=spec.name,
+        name=spec.name.replace("_", " "),
+        description=spec.description,
+        tags=list(dict.fromkeys([*spec.tags, "security", "sbom"])),
+        input_modes=["text/plain"],
+        output_modes=["application/json"],
+    )
+
+
+def build_a2a_apps(
+    report: Report,
+    *,
+    models: ModelSet,
+    registry: AgentRegistry,
+    base_url: str = "http://127.0.0.1:8770",
+) -> dict[str, FastA2A]:
+    """``{"": orchestrator app, "<name>": specialist app, ...}`` keyed by mount name."""
+    from startup_sbom import __version__
+
+    deps = AgentDeps(index=ReportIndex(report))
+    apps: dict[str, FastA2A] = {}
+    orchestrator = build_orchestrator(registry, models)
+    apps[""] = agent_app(
+        orchestrator,
+        deps,
+        name="startup-sbom-orchestrator",
+        description=(
+            "Lead analyst over one startup-sbom scan report: delegates to specialists "
+            "and returns one grounded, machine-checked assessment (read-only)."
+        ),
+        url=base_url,
+        skills=[_skill(spec) for spec in registry.specs()],
+        version=__version__,
+        extra_toolsets=False,  # the orchestrator already owns its toolsets
+    )
+    for spec in registry.specs():
+        if spec.build is None:
+            continue  # remote agents are consumed, never re-exposed
+        model = models.orchestrator if spec.tier != "cheap" else models.specialist
+        apps[spec.name] = agent_app(
+            spec.build(model),
+            deps,
+            name=f"startup-sbom-{spec.name.replace('_', '-')}",
+            description=spec.description,
+            url=f"{base_url}/agents/{spec.name}",
+            skills=[_skill(spec)],
+            version=__version__,
+            extra_toolsets=spec.inject_report_tools,
+        )
+    return apps
+
+
+def build_a2a_app(
+    report: Report,
+    *,
+    models: ModelSet,
+    registry: AgentRegistry,
+    base_url: str = "http://127.0.0.1:8770",
+    token: str | None = None,
+    extra_routes: Sequence[BaseRoute] = (),
+) -> ASGIApp:
+    """One ASGI app: orchestrator at ``/``, specialists at ``/agents/<name>``.
+
+    Mounted Starlette apps get no lifespan events, so the parent lifespan enters each
+    sub-app's lifespan (task manager, ``agent.override(deps=...)``, worker) itself.
+    ``extra_routes`` (e.g. a ``Mount("/acp", ...)``) are matched before the root app.
+    """
+    apps = build_a2a_apps(report, models=models, registry=registry, base_url=base_url)
+
+    @asynccontextmanager
+    async def lifespan(_: Starlette) -> AsyncIterator[None]:
+        async with AsyncExitStack() as stack:
+            for sub in apps.values():
+                await stack.enter_async_context(sub.router.lifespan_context(sub))
+            yield
+
+    routes: list[BaseRoute] = [
+        Mount(f"/agents/{name}", app=sub) for name, sub in apps.items() if name
+    ]
+    routes.extend(extra_routes)
+    routes.append(Mount("/", app=apps[""]))
+    app: ASGIApp = Starlette(routes=routes, lifespan=lifespan)
+    if token:
+        app = TokenAuthMiddleware(app, token)
+    return app

startup_sbom/ai/acp.py

@@ -0,0 +1,274 @@
+"""ACP REST facade: serve the agent registry over the Agent Communication Protocol.
+
+``acp-sdk`` is archived (it merged into A2A in 2025 and breaks on uvicorn >= 0.35), so
+this is a dependency-free Starlette implementation of the subset ACP clients use:
+``GET /ping``, ``GET /agents``, ``GET /agents/{name}`` (manifest), ``POST /runs``
+(``sync`` | ``async`` | ``stream``) and ``GET /runs/{id}``.  Only *local* agents
+(built-ins and allow-listed plugins) are exposed; remote agents are never proxied.
+
+Binds 127.0.0.1 by default.  A bearer token (``STARTUP_SBOM_AGENT_TOKEN``) is
+optional on loopback and **required** on any other interface.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import ipaddress
+import json
+import uuid
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+from startup_sbom.ai import INSTALL_HINT, AIConfigError, AIUnavailableError
+from startup_sbom.ai.index import ReportIndex, sanitize
+from startup_sbom.ai.orchestrator import ModelSet, build_orchestrator
+from startup_sbom.ai.registry import AgentRegistry, AgentSpec
+from startup_sbom.ai.tools import AgentDeps, report_toolset
+from startup_sbom.models import Report
+from startup_sbom.textsafe import clean
+
+try:
+    from pydantic import BaseModel
+    from starlette.applications import Starlette
+    from starlette.requests import Request
+    from starlette.responses import JSONResponse, Response, StreamingResponse
+    from starlette.routing import Route
+    from starlette.types import ASGIApp, Receive, Scope, Send
+except ImportError as exc:  # pragma: no cover - exercised only without the extra
+    raise AIUnavailableError(f"the agent servers need 'starlette': {INSTALL_HINT}") from exc
+
+MAX_BODY_BYTES = 262_144
+MAX_PROMPT_CHARS = 20_000
+TOKEN_ENV = "STARTUP_SBOM_AGENT_TOKEN"  # noqa: S105 - env var name, not a secret
+
+
+def is_loopback_host(host: str) -> bool:
+    """Whether ``host`` only binds/means the loopback interface."""
+    if host in ("localhost", "localhost.localdomain"):
+        return True
+    try:
+        return ipaddress.ip_address(host.strip("[]")).is_loopback
+    except ValueError:
+        return False
+
+
+def require_token(host: str, token: str | None) -> None:
+    """Refuse to serve agents on a non-loopback interface without a bearer token."""
+    if token is None and not is_loopback_host(host):
+        raise AIConfigError(
+            f"refusing to bind {host!r} without authentication: set {TOKEN_ENV} (or bind 127.0.0.1)"
+        )
+
+
+class TokenAuthMiddleware:
+    """Require ``Authorization: Bearer <token>`` on every request."""
+
+    def __init__(self, app: ASGIApp, token: str) -> None:
+        self.app = app
+        self._expected = f"Bearer {token}".encode()
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] == "http":
+            headers = dict(scope.get("headers") or [])
+            if headers.get(b"authorization") != self._expected:
+                response = JSONResponse(
+                    {"code": "unauthorized", "message": "missing or wrong bearer token"},
+                    status_code=401,
+                )
+                await response(scope, receive, send)
+                return
+        await self.app(scope, receive, send)
+
+
+# --------------------------------------------------------------------------- facade
+Runner = Callable[[str], Awaitable[tuple[str, str]]]
+
+
+@dataclass(frozen=True)
+class _Served:
+    manifest: dict[str, Any]
+    run: Runner
+
+
+def _manifest(spec: AgentSpec) -> dict[str, Any]:
+    return {
+        "name": spec.name,
+        "description": spec.description,
+        "metadata": {
+            "tags": list(spec.tags),
+            "framework": "pydantic-ai",
+            "capabilities": [{"name": "grounded-analysis"}],
+            "author": {"name": "startup-sbom"},
+        },
+        "input_content_types": ["text/plain"],
+        "output_content_types": ["application/json"],
+    }
+
+
+def _runner(spec: AgentSpec, models: ModelSet, deps: AgentDeps) -> Runner:
+    model = models.orchestrator if spec.tier != "cheap" else models.specialist
+
+    async def run(prompt: str) -> tuple[str, str]:
+        assert spec.build is not None  # noqa: S101 - remote specs are filtered out
+        agent = spec.build(model)
+        toolsets = [report_toolset()] if spec.inject_report_tools else None
+        result = await agent.run(prompt, deps=deps, toolsets=toolsets)
+        output = result.output
+        if isinstance(output, BaseModel):
+            return output.model_dump_json(), "application/json"
+        return json.dumps(sanitize(output), default=str), "application/json"
+
+    return run
+
+
+def _now() -> str:
+    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
+
+
+def _error(code: str, message: str, status: int) -> JSONResponse:
+    return JSONResponse({"code": code, "message": message}, status_code=status)
+
+
+def build_acp_app(
+    report: Report,
+    *,
+    models: ModelSet,
+    registry: AgentRegistry,
+    include_orchestrator: bool = True,
+    token: str | None = None,
+) -> ASGIApp:
+    """The ACP facade app over ``registry`` (local agents) plus the orchestrator."""
+    deps = AgentDeps(index=ReportIndex(report))
+    served: dict[str, _Served] = {}
+    for spec in registry.specs():
+        if spec.build is None:
+            continue  # never proxy remote agents
+        served[spec.name] = _Served(_manifest(spec), _runner(spec, models, deps))
+    if include_orchestrator:
+        orchestrator = build_orchestrator(registry, models)
+
+        async def run_orchestrator(prompt: str) -> tuple[str, str]:
+            result = await orchestrator.run(prompt, deps=deps)
+            return result.output.model_dump_json(), "application/json"
+
+        served["orchestrator"] = _Served(
+            {
+                "name": "orchestrator",
+                "description": (
+                    "Lead analyst: delegates to the specialists and synthesises one "
+                    "grounded assessment of the loaded scan report"
+                ),
+                "metadata": {"tags": ["orchestrator"], "framework": "pydantic-ai"},
+                "input_content_types": ["text/plain"],
+                "output_content_types": ["application/json"],
+            },
+            run_orchestrator,
+        )
+    runs: dict[str, dict[str, Any]] = {}
+    background: set[asyncio.Task[None]] = set()
+
+    async def ping(_: Request) -> Response:
+        return JSONResponse({})
+
+    async def list_agents(_: Request) -> Response:
+        return JSONResponse({"agents": [s.manifest for s in served.values()]})
+
+    async def get_agent(request: Request) -> Response:
+        entry = served.get(request.path_params["name"])
+        if entry is None:
+            return _error("not_found", "agent not found", 404)
+        return JSONResponse(entry.manifest)
+
+    async def get_run(request: Request) -> Response:
+        run = runs.get(request.path_params["run_id"])
+        if run is None:
+            return _error("not_found", "run not found", 404)
+        return JSONResponse(run)
+
+    async def create_run(request: Request) -> Response:
+        body_bytes = await request.body()
+        if len(body_bytes) > MAX_BODY_BYTES:
+            return _error("invalid_input", "request body too large", 413)
+        try:
+            body = json.loads(body_bytes)
+        except ValueError:
+            return _error("invalid_input", "body is not JSON", 400)
+        if not isinstance(body, dict):
+            return _error("invalid_input", "body must be a JSON object", 400)
+        entry = served.get(str(body.get("agent_name", "")))
+        if entry is None:
+            return _error("not_found", "agent not found", 404)
+        parts = [
+            str(part.get("content") or "")
+            for message in body.get("input") or []
+            if isinstance(message, dict)
+            for part in message.get("parts") or []
+            if isinstance(part, dict)
+        ]
+        prompt = clean("\n".join(parts), max_len=MAX_PROMPT_CHARS, keep_newlines=True)
+        run: dict[str, Any] = {
+            "run_id": str(uuid.uuid4()),
+            "agent_name": body["agent_name"],
+            "session_id": body.get("session_id"),
+            "status": "in-progress",
+            "output": [],
+            "error": None,
+            "created_at": _now(),
+            "finished_at": None,
+        }
+        runs[run["run_id"]] = run
+
+        async def execute() -> None:
+            try:
+                content, ctype = await entry.run(prompt)
+                run["output"] = [
+                    {
+                        "role": f"agent/{run['agent_name']}",
+                        "parts": [{"content_type": ctype, "content": content}],
+                        "created_at": _now(),
+                        "completed_at": _now(),
+                    }
+                ]
+                run["status"] = "completed"
+            except Exception as exc:  # noqa: BLE001 - reported to the caller as a failed run
+                run["status"] = "failed"
+                run["error"] = {
+                    "code": "server_error",
+                    "message": clean(str(exc), max_len=300),
+                }
+            run["finished_at"] = _now()
+
+        mode = body.get("mode", "sync")
+        if mode == "async":
+            task = asyncio.create_task(execute())
+            background.add(task)
+            task.add_done_callback(background.discard)
+            return JSONResponse(run, status_code=202)
+        if mode == "stream":
+
+            async def sse() -> Any:
+                yield f"data: {json.dumps({'type': 'run.created', 'run': run})}\n\n"
+                await execute()
+                for message in run["output"]:
+                    for part in message["parts"]:
+                        yield f"data: {json.dumps({'type': 'message.part', 'part': part})}\n\n"
+                yield f"data: {json.dumps({'type': 'run.' + run['status'], 'run': run})}\n\n"
+
+            return StreamingResponse(sse(), media_type="text/event-stream")
+        await execute()
+        return JSONResponse(run)
+
+    app: ASGIApp = Starlette(
+        routes=[
+            Route("/ping", ping),
+            Route("/agents", list_agents),
+            Route("/agents/{name}", get_agent),
+            Route("/runs", create_run, methods=["POST"]),
+            Route("/runs/{run_id}", get_run),
+        ]
+    )
+    if token:
+        app = TokenAuthMiddleware(app, token)
+    return app