@ngocsangairvds/vsaf 3.2.14 → 3.2.16

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/models/template.py

@@ -1,477 +0,0 @@
-"""Audit Template Models.
-
-This module defines the core data models for audit templates, including
-AuditCheck, AuditSection, and AuditTemplate, with comprehensive validation
-and severity-based weight fallback support.
-
-Reference: design.md Section 6.2
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-from pydantic import AliasChoices, BaseModel, Field, model_validator
-
-from vds_audit_orchestrator.models.enums import (
-    MigrationEffort,
-    Priority,
-    Severity,
-)
-
-
-class CheckApplicability(BaseModel):
-    """Applicability rules for a check based on project profile."""
-
-    included_domains: list[str] | None = Field(default=None, description="Domains where check applies")
-    excluded_domains: list[str] | None = Field(default=None, description="Domains where check is skipped")
-    included_project_types: list[str] | None = Field(default=None, description="Project types where check applies")
-    excluded_project_types: list[str] | None = Field(default=None, description="Project types where check is skipped")
-    included_tech_stacks: list[str] | None = Field(default=None, description="Tech stacks where check applies")
-    excluded_tech_stacks: list[str] | None = Field(default=None, description="Tech stacks where check is skipped")
-    min_risk_level: str | None = Field(default=None, description="Minimum risk level for check")
-
-
-class AuditCheck(BaseModel):
-    """Represents an individual audit check within a section.
-
-    Attributes:
-        id: Unique check identifier (e.g., "BP-001")
-        name: Human-readable check name
-        description: Detailed description of what the check validates
-        max_points: Maximum points achievable for this check (must be >= 0)
-        weight: Relative weight within section (0.0-100.0). If None, severity-based
-            fallback is applied: Critical=10, High=7.5, Medium=5, Low=2.5
-        check_type: Type of check (e.g., "bitbucket_branch_permission",
-            "git_file_exists", "sonarqube_quality_gate")
-        section_id: ID of the parent section this check belongs to
-        requirement_category: Main requirement category (Tiêu chí chính)
-        check_config: Configuration parameters for the check plugin
-        score_mode: Scoring mode: binary, threshold, ratio, range, maturity
-        score_config: Mode-specific scoring configuration
-        required: Whether this is a required check (affects compliance_gate policy)
-        tags: Framework tags (e.g., "SSDF", "OpenSSF", "security")
-        severity: Severity level for failed findings
-        priority: Remediation priority (P1=immediate, P4=low)
-        migration_effort: Estimated effort to fix (Low=<1 day, Very High=>5 days)
-    """
-
-    id: str = Field(..., description="Unique check identifier")
-    name: str | None = None
-    description: str
-    max_points: int = Field(100, ge=0, description="Maximum points achievable")
-    weight: float | None = Field(
-        default=None,
-        ge=0.0,
-        le=100.0,
-        description="Relative weight within section (0-100), None uses severity fallback",
-    )
-    check_type: str | None = Field(
-        default=None,
-        validation_alias=AliasChoices("check_type", "plugin", "plugin_name"),
-    )
-    section_id: str | None = None
-    requirement_category: str | None = Field(
-        default=None,
-        description="Main requirement category (Tiêu chí chính)",
-    )
-    check_config: dict[str, Any] = Field(
-        default_factory=dict,
-        validation_alias=AliasChoices("check_config", "plugin_config"),
-        description="Configuration parameters for check execution",
-    )
-    score_mode: str | None = Field(
-        default=None,
-        description="Scoring mode: binary, threshold, ratio, range, maturity",
-    )
-    score_config: dict[str, Any] = Field(
-        default_factory=dict,
-        description="Mode-specific scoring configuration",
-    )
-    required: bool = Field(
-        default=False,
-        description="Required check (affects compliance_gate policy)",
-    )
-    enabled: bool = Field(
-        default=True,
-        description="Whether the check is enabled for execution",
-    )
-    tags: list[str] = Field(
-        default_factory=list,
-        description="Framework tags (SSDF, OpenSSF, etc.)",
-    )
-    severity: Severity = Field(
-        default=Severity.MEDIUM,
-        description="Severity level for findings",
-    )
-    priority: Priority = Field(
-        default=Priority.P3,
-        description="Remediation priority",
-    )
-    migration_effort: MigrationEffort = Field(
-        default=MigrationEffort.MEDIUM,
-        description="Estimated effort to fix",
-    )
-    remediation_steps: str | None = Field(
-        default=None,
-        description="Optional remediation guidance",
-    )
-    doc_link: str | None = Field(
-        default=None,
-        description="Optional documentation link",
-    )
-    applicability: CheckApplicability | None = Field(
-        default=None,
-        description="Optional applicability rules for profile-based filtering",
-    )
-    row_key: str | None = Field(
-        default=None,
-        description="Stable checklist row key for deterministic rerun/merge correlation",
-    )
-    criterion_path: list[str] = Field(
-        default_factory=list,
-        description="Normalized checklist hierarchy path for this check",
-    )
-    hierarchy_depth: int = Field(
-        default=0,
-        ge=0,
-        description="Hierarchy depth derived from criterion_path",
-    )
-
-    @model_validator(mode="after")
-    def _ensure_name(self) -> AuditCheck:
-        if not self.name:
-            self.name = self.description
-        return self
-
-    @property
-    def plugin_name(self) -> str | None:
-        return self.check_type
-
-    @plugin_name.setter
-    def plugin_name(self, value: str | None) -> None:
-        self.check_type = value
-
-    @property
-    def plugin_config(self) -> dict[str, Any]:
-        return self.check_config
-
-    @plugin_config.setter
-    def plugin_config(self, value: dict[str, Any]) -> None:
-        self.check_config = value
-
-    @property
-    def effective_weight(self) -> float:
-        """Get effective weight using severity-based fallback.
-
-        Returns the configured weight, or computes a default based on severity:
-        - Critical: 10.0
-        - High: 7.5
-        - Medium: 5.0
-        - Low: 2.5
-
-        These values align with OpenSSF Scorecard risk weighting and are
-        normalized within the section during template validation.
-        """
-        if self.weight is not None:
-            return self.weight
-
-        # Severity-based fallback (OpenSSF Scorecard aligned)
-        severity_weights: dict[Severity, float] = {
-            Severity.CRITICAL: 10.0,
-            Severity.HIGH: 7.5,
-            Severity.MEDIUM: 5.0,
-            Severity.LOW: 2.5,
-        }
-        return severity_weights.get(self.severity, 5.0)
-
-
-class AuditSection(BaseModel):
-    """Represents a category/group of related audit checks.
-
-    Sections aggregate check scores using configurable policies and can
-    apply score caps for critical failures.
-
-    Attributes:
-        id: Unique section identifier (e.g., "security", "governance")
-        name: Human-readable section name
-        description: Detailed section description
-        weight: Relative weight of this section in overall score (0.0-100.0)
-        scoring_policy: How to aggregate check scores:
-            - weighted_mean: Default - weighted average of check scores
-            - maturity: Maturity model aggregation by practice_id
-            - compliance_gate: All required checks must pass or cap applied
-        target_score: Optional maturity target percent (0-100) for tracking
-        score_cap: Maximum allowed score percent (0-100) when critical checks fail.
-            Defaults by tag: security=60, compliance=0 (fail closed)
-        confidence_mode: How to compute section confidence:
-            - coverage: Based on ERROR check ratio
-            - confidence: Average of check.confidence values
-            - both: Multiply coverage and confidence factors
-        tags: Section tags for default policies (security, compliance, etc.)
-        checks: List of audit checks in this section
-    """
-
-    id: str
-    name: str = Field(..., validation_alias=AliasChoices("name", "title"))
-    description: str = ""
-    weight: float = Field(
-        ...,
-        ge=0.0,
-        le=100.0,
-        description="Relative weight in overall score (sum of all = 100.0)",
-    )
-    scoring_policy: str = Field(
-        default="weighted_mean",
-        description="Aggregation policy: weighted_mean, maturity, compliance_gate",
-    )
-    target_score: float | None = Field(
-        default=None,
-        ge=0.0,
-        le=100.0,
-        description="Optional maturity target percent for tracking progress",
-    )
-    score_cap: float | None = Field(
-        default=None,
-        ge=0.0,
-        le=100.0,
-        description="Max score when critical checks fail (default by tag)",
-    )
-    confidence_mode: str = Field(
-        default="coverage",
-        description="Confidence calculation: coverage, confidence, or both",
-    )
-    tags: list[str] = Field(
-        default_factory=list,
-        description="Section tags for default policy application",
-    )
-    checks: list[AuditCheck] = Field(
-        default_factory=list,
-        description="Audit checks belonging to this section",
-    )
-
-    @model_validator(mode="after")
-    def _normalize_check_weights(self) -> AuditSection:
-        if not self.checks:
-            return self
-
-        has_explicit_weights = any(check.weight is not None for check in self.checks)
-        if has_explicit_weights:
-            for check in self.checks:
-                if check.weight is None:
-                    check.weight = check.effective_weight
-        else:
-            for check in self.checks:
-                check.weight = check.effective_weight
-
-        total_weight = sum(check.weight or 0.0 for check in self.checks)
-        if total_weight > 0:
-            for check in self.checks:
-                if check.weight is not None:
-                    check.weight = (check.weight / total_weight) * 100.0
-        return self
-
-    @property
-    def title(self) -> str:
-        return self.name
-
-    @title.setter
-    def title(self, value: str) -> None:
-        self.name = value
-
-    @property
-    def default_score_cap(self) -> float | None:
-        """Get default score cap based on section tags.
-
-        Returns:
-            - 60.0 if 'security' tag present
-            - 0.0 if 'compliance' tag present (fail closed)
-            - None otherwise (no cap)
-        """
-        tag_caps: dict[str, float] = {
-            "security": 60.0,
-            "compliance": 0.0,
-        }
-        for tag in self.tags:
-            if tag.lower() in tag_caps:
-                return tag_caps[tag.lower()]
-        return None
-
-    @property
-    def effective_score_cap(self) -> float | None:
-        """Get effective score cap (explicit or default)."""
-        return self.score_cap if self.score_cap is not None else self.default_score_cap
-
-
-class AuditTemplate(BaseModel):
-    """Main audit template containing sections and validation logic.
-
-    The template defines the complete audit structure with section weights,
-    check definitions, and comprehensive validation including severity-based
-    weight fallback for missing check weights.
-
-    Attributes:
-        name: Template name/identifier
-        version: Template version string (semver recommended)
-        sections: List of audit sections defining the audit structure
-
-    Example:
-        >>> template = AuditTemplate(
-        ...     name="VDS Base Audit",
-        ...     version="1.0.0",
-        ...     sections=[...]
-        ... )
-        >>> # Weights are auto-validated and normalized
-    """
-
-    name: str
-    version: str = "1.0.0"
-    strict_weights: bool = Field(
-        default=False,
-        description="If True, bypasses weight normalization (respects original values)",
-    )
-    sections: list[AuditSection] = Field(
-        default_factory=list,
-        description="Audit sections defining the template structure",
-    )
-
-    @model_validator(mode="after")
-    def validate_weights(self) -> AuditTemplate:
-        """Validate section weights and normalize check weights.
-
-        Validation rules:
-        1. Section weights must sum to 100.0 (within tolerance)
-        2. For each section:
-           - If any check has explicit weight, all must (or use defaults)
-           - Apply severity-based fallback for missing weights
-           - Normalize weights to sum to 100.0 within the section
-        3. Empty sections are allowed (no checks to validate)
-
-        If strict_weights is True, normalization logic is skipped to preserve
-        original values (e.g., from Confluence checklist).
-
-        Raises:
-            ValueError: If section weights don't sum to 100.0 (unless strict_weights=True)
-        """
-        if self.strict_weights:
-            return self
-
-        WEIGHT_TOLERANCE = 0.1
-
-        # Validate section weights sum
-        section_weight_sum = sum(s.weight for s in self.sections)
-
-        # Allow 1.0 based weights (normalize to 100.0)
-        if self.sections and abs(section_weight_sum - 1.0) < WEIGHT_TOLERANCE:
-            for s in self.sections:
-                s.weight *= 100.0
-            section_weight_sum = sum(s.weight for s in self.sections)
-
-        if self.sections and abs(section_weight_sum - 100.0) > WEIGHT_TOLERANCE:
-            # Allow 1.0 based weights (normalize to 100.0)
-            if abs(section_weight_sum - 1.0) < WEIGHT_TOLERANCE:
-                for s in self.sections:
-                    s.weight *= 100.0
-            else:
-                raise ValueError(
-                    f"Section weights must sum to 100.0, got {section_weight_sum:.2f}. "
-                    f"Please adjust section weights in the template."
-                )
-
-        # Normalize check weights within each section
-        for section in self.sections:
-            if not section.checks:
-                continue
-
-            # Separate checks with and without explicit weights
-            has_explicit_weights = any(c.weight is not None for c in section.checks)
-
-            if has_explicit_weights:
-                # Use explicit weights, apply severity fallback for None
-                for check in section.checks:
-                    if check.weight is None:
-                        # Use severity-based effective weight
-                        check.weight = check.effective_weight
-
-                # Normalize to sum to 100.0 within section
-                total_weight = sum(c.weight or 0.0 for c in section.checks)
-                if total_weight > 0:
-                    for check in section.checks:
-                        if check.weight is not None:
-                            check.weight = (check.weight / total_weight) * 100.0
-            else:
-                # All checks use severity-based weights, then normalize
-                raw_weights = [check.effective_weight for check in section.checks]
-                total_raw = sum(raw_weights)
-
-                if total_raw > 0:
-                    for check, raw_weight in zip(section.checks, raw_weights, strict=True):
-                        check.weight = (raw_weight / total_raw) * 100.0
-
-        return self
-
-    @property
-    def total_checks(self) -> int:
-        """Total number of checks across all sections."""
-        return sum(len(s.checks) for s in self.sections)
-
-    @property
-    def required_checks(self) -> list[AuditCheck]:
-        """All required checks across all sections."""
-        return [check for section in self.sections for check in section.checks if check.required]
-
-    def get_section_by_id(self, section_id: str) -> AuditSection | None:
-        """Get section by ID.
-
-        Args:
-            section_id: Section identifier to find
-
-        Returns:
-            The section if found, None otherwise
-        """
-        for section in self.sections:
-            if section.id == section_id:
-                return section
-        return None
-
-    def get_check_by_id(self, check_id: str) -> AuditCheck | None:
-        """Get check by ID across all sections.
-
-        Args:
-            check_id: Check identifier to find
-
-        Returns:
-            The check if found, None otherwise
-        """
-        for section in self.sections:
-            for check in section.checks:
-                if check.id == check_id:
-                    return check
-        return None
-
-    def get_checks_by_tag(self, tag: str) -> list[AuditCheck]:
-        """Get all checks with a specific tag.
-
-        Args:
-            tag: Tag to filter by
-
-        Returns:
-            List of checks with the specified tag
-        """
-        return [
-            check
-            for section in self.sections
-            for check in section.checks
-            if tag.lower() in (t.lower() for t in check.tags)
-        ]
-
-    def get_sections_by_tag(self, tag: str) -> list[AuditSection]:
-        """Get all sections with a specific tag.
-
-        Args:
-            tag: Tag to filter by
-
-        Returns:
-            List of sections with the specified tag
-        """
-        return [section for section in self.sections if tag.lower() in (t.lower() for t in section.tags)]

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/observability/__init__.py

@@ -1,31 +0,0 @@
-"""Observability surface for VDS Audit Orchestrator.
-
-Phase 9d cleanup: the audit-specific tracing wrapper was deleted in favor of
-direct use of ``vds_agent_core.observability.AgentTracer``. This package now
-owns only audit-specific Prometheus metrics; tracing primitives are imported
-from ``vds_agent_core.observability`` at call sites, with audit context vars
-merged via ``vds_audit_orchestrator.logging_config.audit_otel_span`` /
-``audit_trace_attrs``.
-"""
-
-from vds_audit_orchestrator.observability.metrics import (
-    AUDIT_DURATION,
-    CHECK_DURATION,
-    DSPY_ROWS_ACCEPTED,
-    DSPY_ROWS_REJECTED_TO_FALLBACK,
-    DSPY_ROWS_TOTAL,
-    GAPS_FOUND,
-    LLM_TOKENS_USED,
-    init_metrics,
-)
-
-__all__ = [
-    "AUDIT_DURATION",
-    "CHECK_DURATION",
-    "DSPY_ROWS_ACCEPTED",
-    "DSPY_ROWS_REJECTED_TO_FALLBACK",
-    "DSPY_ROWS_TOTAL",
-    "GAPS_FOUND",
-    "LLM_TOKENS_USED",
-    "init_metrics",
-]