dockerls 1.0.0__py3-none-any.whl

dockerls/domain/entities/scan_result.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel
+
+from dockerls.domain.entities.vulnerability import Severity, Vulnerability
+
+
+class ScanStatus(StrEnum):
+    OK = "OK"
+    ERROR = "ERROR"
+    TIMEOUT = "TIMEOUT"
+    PARTIAL = "PARTIAL"
+
+
+class ScanErrorKind(StrEnum):
+    """Why a scan failed, as a stable code rather than a slice of stderr.
+
+    A terminal column can only hold a few characters, and truncating the raw
+    message produced things like `error in v...` -- which names no cause and
+    cannot be grouped, counted, or acted on. The full stderr is still kept in
+    `error_message` (log file and `--format json`); this is what the table
+    shows instead of a cut-off prefix.
+
+    It also decides *retryability*: a broken vulnerability database is the
+    scanner's problem and another scanner may well succeed, while a tag that
+    does not exist will fail identically no matter who is asked.
+    """
+
+    NONE = "NONE"
+    DB_INIT_FAILED = "DB_INIT_FAILED"
+    TIMEOUT = "TIMEOUT"
+    AUTH_REQUIRED = "AUTH_REQUIRED"
+    NOT_FOUND = "NOT_FOUND"
+    RATE_LIMITED = "RATE_LIMITED"
+    INVALID_OUTPUT = "INVALID_OUTPUT"
+    SCANNER_MISSING = "SCANNER_MISSING"
+    #: The reference named a host the network policy refuses to contact.
+    #: The scan never ran, so this is an absence of measurement like any
+    #: other error -- and it is *not* a scanner fault: a second tool would
+    #: pull from exactly the same refused host.
+    BLOCKED_BY_POLICY = "BLOCKED_BY_POLICY"
+    UNKNOWN = "UNKNOWN"
+
+    @property
+    def is_scanner_fault(self) -> bool:
+        """True when a *different* scanner has a real chance of succeeding.
+
+        `NOT_FOUND` and `AUTH_REQUIRED` are facts about the image, so retrying
+        them with another tool just doubles the wait for the same answer.
+        """
+        return self in (
+            ScanErrorKind.DB_INIT_FAILED,
+            ScanErrorKind.TIMEOUT,
+            ScanErrorKind.RATE_LIMITED,
+            ScanErrorKind.INVALID_OUTPUT,
+            ScanErrorKind.SCANNER_MISSING,
+            ScanErrorKind.UNKNOWN,
+        )
+
+
+class ScanResult(BaseModel):
+    image_reference: str
+    scanner: str = "trivy"
+    vulnerabilities: list[Vulnerability] = []
+    scan_timestamp: str = ""
+    status: ScanStatus = ScanStatus.OK
+    error_message: str = ""
+    # Classified reason for a failure. `error_message` keeps the full stderr;
+    # this is the part that fits in a table and can be grouped across tags.
+    error_kind: ScanErrorKind = ScanErrorKind.NONE
+    # Path to the raw scanner JSON this result was parsed from, so a score
+    # shown to the user can always be traced back to its source evidence.
+    evidence_path: str = ""
+    # Base distribution the scanner identified ("debian", "alpine", "wolfi")
+    # and its version. This is the only *measured* source of the image's
+    # libc family, which is what decides whether a migration between two
+    # images can work at all -- an Alpine-to-Debian move swaps musl for
+    # glibc, and native modules compiled against one do not load under the
+    # other. Empty when the scanner did not report it.
+    os_family: str = ""
+    os_version: str = ""
+
+    @property
+    def is_verified(self) -> bool:
+        """A scan that actually completed and produced a parsed result.
+
+        This is the gate for recommending an image: only a scanner run that
+        exited cleanly (`OK`) and carries a timestamp counts as proof. A
+        `PARTIAL` scan is usable for reporting but is deliberately *not*
+        verified -- it means some targets could not be inspected, so its
+        vulnerability counts are a lower bound, not a measurement.
+        """
+        return self.status is ScanStatus.OK and bool(self.scan_timestamp)
+
+    @property
+    def critical_count(self) -> int:
+        return sum(1 for v in self.vulnerabilities if v.severity == Severity.CRITICAL)
+
+    @property
+    def high_count(self) -> int:
+        return sum(1 for v in self.vulnerabilities if v.severity == Severity.HIGH)
+
+    @property
+    def medium_count(self) -> int:
+        return sum(1 for v in self.vulnerabilities if v.severity == Severity.MEDIUM)
+
+    @property
+    def low_count(self) -> int:
+        return sum(1 for v in self.vulnerabilities if v.severity == Severity.LOW)
+
+    @property
+    def total_count(self) -> int:
+        return len(self.vulnerabilities)
+
+    @property
+    def fixable_count(self) -> int:
+        return sum(1 for v in self.vulnerabilities if v.is_fixable)
+
+    @property
+    def fixable_high_count(self) -> int:
+        return sum(1 for v in self.vulnerabilities if v.severity == Severity.HIGH and v.is_fixable)
+
+    @property
+    def fixable_critical_count(self) -> int:
+        return sum(
+            1 for v in self.vulnerabilities if v.severity == Severity.CRITICAL and v.is_fixable
+        )

dockerls/domain/entities/vulnerability.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import math
+from enum import StrEnum
+from typing import Any
+
+from loguru import logger
+from pydantic import BaseModel, Field, field_validator
+
+from dockerls.domain.value_objects.tristate import Tristate
+
+
+def _probability(value: Any, field: str) -> float:
+    """Coerce an externally supplied probability into 0.0-1.0, or to zero.
+
+    EPSS arrives as JSON from a third party, and `float()` happily accepts
+    `"nan"`, `"inf"` and `"-1"`. None of the three is a probability, and all
+    three used to reach the scoring engine, where the damage was not
+    cosmetic:
+
+    * `NaN` propagates through the penalty sum, and the final
+      `max(0.0, min(100.0, score))` answers **100.0** for a NaN input --
+      every comparison against NaN is False, so the clamp keeps its own
+      bound. A malformed feed therefore certified an image as perfect.
+    * A negative probability *subtracts* from the penalty, so a feed
+      answering `-5` raises the score of an image with more findings.
+
+    Both are the same failure this codebase is built to refuse: a source
+    that did not give a usable answer being spent as evidence of safety. An
+    unusable value becomes 0.0, which contributes nothing in either
+    direction, and is loud in the log rather than silent.
+    """
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        number = math.nan
+    if not math.isfinite(number) or not (0.0 <= number <= 1.0):
+        logger.warning(f"Discarding out-of-range {field} value {value!r}; treated as no signal")
+        return 0.0
+    return number
+
+
+class Severity(StrEnum):
+    CRITICAL = "CRITICAL"
+    HIGH = "HIGH"
+    MEDIUM = "MEDIUM"
+    LOW = "LOW"
+    UNKNOWN = "UNKNOWN"
+
+
+class FixStatus(StrEnum):
+    FIX_AVAILABLE = "FIX_AVAILABLE"
+    NO_FIX = "NO_FIX"
+    UNDER_INVESTIGATION = "UNDER_INVESTIGATION"
+
+
+class PackageOrigin(StrEnum):
+    """De onde vem o pacote afetado -- o que determina como se remedia."""
+
+    OS = "os"
+    LANGUAGE = "lang-pkg"
+    UNKNOWN = "unknown"
+
+
+# Marcadores vindos do `Class`/`Type`/`Target` do Trivy e do `artifact.type`
+# do Grype. Os de linguagem são checados primeiro: um `Target` como
+# "/usr/local/lib/node_modules/npm/package-lock.json" contém tanto "npm"
+# quanto, potencialmente, o nome da distro.
+_LANG_MARKERS = (
+    "lang-pkg",
+    "node-pkg",
+    "npm",
+    "yarn",
+    "python-pkg",
+    "pip",
+    "poetry",
+    "gemspec",
+    "gem",
+    "cargo",
+    "composer",
+    "go-module",
+    "gobinary",
+    "jar",
+    "pom",
+    "conan",
+    "nuget",
+    "swift",
+    "pub",
+    "hex",
+    "site-packages",
+    "node_modules",
+)
+_OS_MARKERS = (
+    "os-pkg",
+    "apk",
+    "deb",
+    "rpm",
+    "alpine",
+    "debian",
+    "ubuntu",
+    "redhat",
+    "centos",
+    "amazon",
+    "suse",
+    "photon",
+    "oracle",
+    "rocky",
+    "alma",
+    "wolfi",
+    "chainguard",
+)
+
+
+class Vulnerability(BaseModel):
+    cve_id: str
+    severity: Severity
+    cvss_score: float = 0.0
+    # Qual base publicou o `cvss_score` acima ("nvd", "redhat", "ghsa", ...).
+    # Severidade e score podem vir de bases diferentes -- é assim que um
+    # CRITICAL aparecia ao lado de um CVSS 7.5 e parecia contradição. Dizer a
+    # origem é o que torna o número verificável em vez de suspeito.
+    cvss_source: str = ""
+    # Origem do pacote: "os" (apk/apt/yum) ou "lang-pkg" (npm, pip, gem...).
+    # Decide a remediação: `apk upgrade` não resolve um CVE de dependência do
+    # npm embutido na imagem.
+    package_type: str = ""
+    target: str = ""
+    package_name: str = ""
+    installed_version: str = ""
+    fixed_version: str = ""
+    description: str = ""
+    published_date: str = ""
+    # Confirmed exploited in the wild (CISA KEV). Kept as the boolean the
+    # scoring engine and the exporters have always read; `kev_status` is the
+    # field that distinguishes "checked, not listed" from "never checked".
+    exploit_known: bool = False
+    # Three-valued, because a threat-intel feed that did not answer must not
+    # look like a feed that answered "no". With the KEV catalogue
+    # unreachable every CVE came back `exploit_known=False`, and the report
+    # then stated -- affirmatively -- that the image had no known-exploited
+    # vulnerabilities. That sentence is the strongest claim this tool makes
+    # about real-world exploitation, and it was being emitted precisely when
+    # nothing had been consulted.
+    kev_status: Tristate = Tristate.UNKNOWN
+    # EPSS probability, 0.0-1.0. `epss_known` says whether the 0.0 means
+    # "FIRST.org scored it at zero" or "FIRST.org was not reachable".
+    epss_score: float = 0.0
+    epss_known: bool = False
+    #: EPSS percentile when the source provides it: 0.9 probability is
+    #: extreme, while the percentile says how extreme relative to everything
+    #: else scored that day.
+    epss_percentile: float = 0.0
+    #: When the intelligence above was retrieved, so a stale enrichment is
+    #: visible rather than assumed current.
+    threat_intel_timestamp: str = ""
+    # Public exploit catalogued in Exploit-DB. Three-valued for the same
+    # reason `kev_status` is: a catalogue that was never consulted must not
+    # read as a catalogue that answered "no exploit". UNKNOWN is the default
+    # precisely so an absent lookup can never be spent as reassurance.
+    #
+    # KEV and this answer different questions and neither replaces the
+    # other: KEV means "observed being exploited in the wild", while an
+    # Exploit-DB entry means "working exploit code is published". A CVE can
+    # sit in one and not the other.
+    exploitdb_status: Tristate = Tristate.UNKNOWN
+    #: The EDB-ID(s) matched, so a reader can open
+    #: https://www.exploit-db.com/exploits/<id> and judge the exploit itself.
+    #: Matching is strictly CVE-ID to CVE-ID -- see the client for why a
+    #: product-name fallback would manufacture false positives.
+    exploitdb_ids: list[str] = Field(default_factory=list)
+    #: Exploit-DB flags entries as verified (someone reproduced it) or not.
+    #: An unverified entry is a weaker signal than a verified one, and
+    #: collapsing the two would overstate what is known. Only meaningful
+    #: when `exploitdb_status` is TRUE.
+    exploitdb_verified: bool = False
+
+    @field_validator("epss_score", "epss_percentile", mode="before")
+    @classmethod
+    def _bound_probabilities(cls, value: Any, info: Any) -> float:
+        """Enforced on the entity, not only where the feed is parsed.
+
+        The same field is rebuilt from the SQLite cache and from scanner
+        JSON, and a row written before this check existed is still on disk.
+        The invariant belongs to the type.
+        """
+        return _probability(value, info.field_name)
+
+    @property
+    def origin(self) -> PackageOrigin:
+        """Whether this finding lives in an OS package or a language package.
+
+        Decide a remediação, e a diferença é total: as vulnerabilidades de
+        `node:22-alpine` estão todas em
+        `/usr/local/lib/node_modules/npm/node_modules/`, isto é, nas
+        dependências do npm que a imagem embute. `apk upgrade` não resolve
+        nenhuma delas. Sem essa distinção, a recomendação aponta para o
+        gerenciador errado.
+        """
+        haystack = f"{self.package_type} {self.target}".lower()
+        if any(marker in haystack for marker in _LANG_MARKERS):
+            return PackageOrigin.LANGUAGE
+        if any(marker in haystack for marker in _OS_MARKERS):
+            return PackageOrigin.OS
+        return PackageOrigin.UNKNOWN
+
+    @property
+    def fix_status(self) -> FixStatus:
+        if self.fixed_version:
+            return FixStatus.FIX_AVAILABLE
+        return FixStatus.NO_FIX
+
+    @property
+    def is_fixable(self) -> bool:
+        return self.fix_status == FixStatus.FIX_AVAILABLE
+
+
+def finding_identity(vuln: Vulnerability) -> str:
+    """Uma identidade estável para um achado, comparável entre medições.
+
+    Id da vulnerabilidade **e** pacote, porque o mesmo CVE afetando dois
+    pacotes de uma imagem são dois problemas a resolver, e o mesmo pacote
+    carregando dois CVEs também. A versão instalada fica de fora de propósito:
+    dois scanners -- e a mesma imagem antes e depois de um build -- reportam o
+    mesmo pacote com strings de versão normalizadas de formas diferentes, e
+    comparar isso fabricaria diferença a partir de formatação.
+
+    Mora aqui, e não no serviço que a inventou, porque duas coisas distintas
+    dependem dela: a validação cruzada entre scanners e a atribuição de cada
+    achado à base ou às suas camadas. Se cada uma tivesse a sua, as duas
+    divergiriam na primeira correção.
+    """
+    return f"{vuln.cve_id.strip().upper()}|{vuln.package_name.strip().lower()}"

dockerls/domain/interfaces/__init__.py

@@ -0,0 +1,17 @@
+from dockerls.domain.interfaces.cache_store import CacheStoreInterface
+from dockerls.domain.interfaces.dockerfile_validator import (
+    DockerfileValidatorInterface,
+    HardeningTemplateProvider,
+)
+from dockerls.domain.interfaces.eol_checker import EOLCheckerInterface
+from dockerls.domain.interfaces.image_repository import ImageRepositoryInterface
+from dockerls.domain.interfaces.scanner import ScannerInterface
+
+__all__ = [
+    "ImageRepositoryInterface",
+    "ScannerInterface",
+    "EOLCheckerInterface",
+    "CacheStoreInterface",
+    "DockerfileValidatorInterface",
+    "HardeningTemplateProvider",
+]

dockerls/domain/interfaces/cache_store.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class CacheStoreInterface(ABC):
+    @abstractmethod
+    async def get(self, key: str) -> Any | None: ...
+
+    @abstractmethod
+    async def set(self, key: str, value: Any, ttl_seconds: int = 86400) -> None: ...
+
+    @abstractmethod
+    async def delete(self, key: str) -> None: ...
+
+    @abstractmethod
+    async def clear(self) -> None: ...

dockerls/domain/interfaces/dockerfile_validator.py

@@ -0,0 +1,99 @@
+"""Interfaces para validação de Dockerfiles."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from dockerls.domain.entities.dockerfile_analysis import (
+        DockerfileAnalysis,
+        DockerfileValidationResult,
+        HardeningRule,
+    )
+
+
+class DockerfileValidatorInterface(ABC):
+    """Interface para validadores de Dockerfile."""
+
+    @abstractmethod
+    def validate(self, dockerfile_path: str | Path) -> DockerfileValidationResult:
+        """Valida um Dockerfile contra regras OWASP.
+
+        Args:
+            dockerfile_path: Caminho para o Dockerfile ou diretório contendo Dockerfile.
+
+        Returns:
+            Resultado da validação com checks, warnings e errors.
+        """
+        pass
+
+    @abstractmethod
+    def analyze(self, dockerfile_path: str | Path) -> DockerfileAnalysis:
+        """Analisa um Dockerfile e retorna análise completa.
+
+        Args:
+            dockerfile_path: Caminho para o Dockerfile ou diretório contendo Dockerfile.
+
+        Returns:
+            Análise completa incluindo info, validação e score de segurança.
+        """
+        pass
+
+    @abstractmethod
+    def suggest_hardening(self, dockerfile_path: str | Path) -> list[HardeningRule]:
+        """Sugere melhorias de hardening para um Dockerfile.
+
+        Args:
+            dockerfile_path: Caminho para o Dockerfile ou diretório contendo Dockerfile.
+
+        Returns:
+            Lista de regras de hardening sugeridas.
+        """
+        pass
+
+
+class HardeningTemplateProvider(ABC):
+    """Interface para provedores de templates hardened."""
+
+    @abstractmethod
+    def get_template(self, base_image: str) -> str:
+        """Retorna template hardened para um tipo de base image.
+
+        Args:
+            base_image: Nome da imagem base (ex: node, python, go).
+
+        Returns:
+            Conteúdo do template Dockerfile hardened.
+        """
+        pass
+
+    @abstractmethod
+    def list_templates(self) -> list[str]:
+        """Lista todos os templates disponíveis.
+
+        Returns:
+            Lista de nomes de templates disponíveis.
+        """
+        pass
+
+    @abstractmethod
+    def generate_hardened_dockerfile(
+        self,
+        dockerfile_path: str | Path,
+        base_image: str | None = None,
+        output_path: str | Path | None = None,
+    ) -> str:
+        """Gera um Dockerfile hardened baseado no original ou template.
+
+        Args:
+            dockerfile_path: Caminho para o Dockerfile original.
+            base_image: Imagem base para usar no template (opcional).
+            output_path: Caminho para salvar o novo Dockerfile (opcional).
+
+        Returns:
+            Conteúdo do Dockerfile hardened gerado.
+        """
+        pass

dockerls/domain/interfaces/eol_checker.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class EOLCheckerInterface(ABC):
+    @abstractmethod
+    async def is_eol(self, product: str, version: str) -> bool: ...
+
+    @abstractmethod
+    async def is_lts(self, product: str, version: str) -> bool: ...

dockerls/domain/interfaces/image_repository.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from dockerls.domain.entities.image import DockerImage
+
+
+class ImageRepositoryInterface(ABC):
+    @abstractmethod
+    async def search_tags(self, image_name: str, limit: int = 100) -> list[DockerImage]: ...
+
+    @abstractmethod
+    async def get_image_metadata(self, image_name: str, tag: str) -> DockerImage | None: ...

dockerls/domain/interfaces/scanner.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from dockerls.domain.entities.scan_result import ScanResult
+
+
+class ScannerInterface(ABC):
+    @abstractmethod
+    async def scan(self, image_reference: str) -> ScanResult: ...
+
+    @abstractmethod
+    async def is_available(self) -> bool: ...