kekkai-cli 1.0.0__py3-none-any.whl

kekkai_core/windows/scoop.py

@@ -0,0 +1,165 @@
+"""Scoop manifest generation and validation for Windows distribution."""
+
+import json
+import re
+from typing import Any
+
+
+def generate_scoop_manifest(
+    version: str,
+    sha256: str,
+    whl_url: str,
+    python_version: str = "3.12",
+) -> dict[str, Any]:
+    """
+    Generate Scoop manifest for Kekkai package.
+
+    Args:
+        version: Package version (e.g., "0.0.1")
+        sha256: SHA256 checksum of the wheel file
+        whl_url: URL to wheel file (typically GitHub release)
+        python_version: Minimum Python version required
+
+    Returns:
+        Scoop manifest as dictionary
+
+    Raises:
+        ValueError: If version format is invalid or URLs are not HTTPS
+    """
+    # Validate version format (basic semver)
+    if not re.match(r"^\d+\.\d+\.\d+(-[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*)?$", version):
+        raise ValueError(f"Invalid version format: {version}")
+
+    # Validate HTTPS URLs only
+    if not whl_url.startswith("https://"):
+        raise ValueError(f"URL must use HTTPS: {whl_url}")
+
+    # Validate SHA256 format (64 hex characters)
+    if not re.match(r"^[a-fA-F0-9]{64}$", sha256):
+        raise ValueError(f"Invalid SHA256 format: {sha256}")
+
+    manifest: dict[str, Any] = {
+        "version": version,
+        "description": "Kekkai - Local-first AppSec orchestration and compliance checker",
+        "homepage": "https://github.com/kademoslabs/kekkai",
+        "license": "MIT",
+        "depends": "python",
+        "url": whl_url,
+        "hash": sha256,
+        "installer": {
+            "script": [
+                "# Validate Python version",
+                (
+                    "$pythonVersion = python --version 2>&1 | "
+                    'Select-String -Pattern "Python (\\d+\\.\\d+)"'
+                ),
+                "$version = [version]$pythonVersion.Matches.Groups[1].Value",
+                f'if ($version -lt [version]"{python_version}") {{',
+                f'    Write-Error "Python {python_version}+ required, found $version"',
+                "    exit 1",
+                "}",
+                "",
+                "# Install Kekkai wheel",
+                f'python -m pip install --force-reinstall --no-deps "{whl_url}"',
+                "if ($LASTEXITCODE -ne 0) {",
+                '    Write-Error "pip install failed"',
+                "    exit 1",
+                "}",
+            ]
+        },
+        "uninstaller": {
+            "script": [
+                "python -m pip uninstall -y kekkai",
+            ]
+        },
+        "checkver": {
+            "github": "https://github.com/kademoslabs/kekkai",
+        },
+        "autoupdate": {
+            "url": "https://github.com/kademoslabs/kekkai/releases/download/v$version/kekkai-$version-py3-none-any.whl",
+        },
+        "notes": [
+            "Kekkai has been installed successfully!",
+            "Run 'kekkai --help' to get started.",
+            "For documentation, visit: https://github.com/kademoslabs/kekkai",
+        ],
+    }
+
+    return manifest
+
+
+def validate_scoop_manifest(manifest: dict[str, Any]) -> bool:
+    """
+    Validate Scoop manifest structure and required fields.
+
+    Args:
+        manifest: Scoop manifest dictionary
+
+    Returns:
+        True if manifest is valid
+
+    Raises:
+        ValueError: If manifest is invalid with detailed error message
+    """
+    # Required fields
+    required_fields = ["version", "description", "homepage", "license", "url", "hash"]
+
+    for field in required_fields:
+        if field not in manifest:
+            raise ValueError(f"Missing required field: {field}")
+
+    # Validate version format
+    version = manifest["version"]
+    if not re.match(r"^\d+\.\d+\.\d+(-[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*)?$", version):
+        raise ValueError(f"Invalid version format: {version}")
+
+    # Validate URL is HTTPS
+    url = manifest["url"]
+    if not url.startswith("https://"):
+        raise ValueError(f"URL must use HTTPS: {url}")
+
+    # Validate SHA256 format
+    sha256 = manifest["hash"]
+    if not re.match(r"^[a-fA-F0-9]{64}$", sha256):
+        raise ValueError(f"Invalid SHA256 format: {sha256}")
+
+    # Validate installer/uninstaller structure
+    if "installer" in manifest and "script" not in manifest["installer"]:
+        raise ValueError("installer must contain 'script' field")
+
+    if "uninstaller" in manifest and "script" not in manifest["uninstaller"]:
+        raise ValueError("uninstaller must contain 'script' field")
+
+    # Validate homepage URL
+    homepage = manifest["homepage"]
+    if not homepage.startswith("https://") and not homepage.startswith("http://"):
+        raise ValueError(f"Invalid homepage URL: {homepage}")
+
+    return True
+
+
+def format_scoop_manifest_json(manifest: dict[str, Any]) -> str:
+    """
+    Format Scoop manifest as pretty-printed JSON.
+
+    Args:
+        manifest: Scoop manifest dictionary
+
+    Returns:
+        JSON string with 2-space indentation
+    """
+    return json.dumps(manifest, indent=2, ensure_ascii=False)
+
+
+def generate_scoop_checksum_file(version: str, sha256: str) -> str:
+    """
+    Generate checksums.txt file for Scoop verification.
+
+    Args:
+        version: Package version
+        sha256: SHA256 checksum
+
+    Returns:
+        Formatted checksum file content
+    """
+    return f"kekkai-{version}-py3-none-any.whl: {sha256}\n"

kekkai_core/windows/validators.py

@@ -0,0 +1,220 @@
+"""Windows-specific validation utilities."""
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+def validate_python_version(
+    required_version: str = "3.12",
+) -> tuple[bool, str]:
+    """
+    Validate that Python version meets minimum requirement.
+
+    Args:
+        required_version: Minimum Python version (e.g., "3.12")
+
+    Returns:
+        Tuple of (is_valid, message)
+    """
+    try:
+        # Get current Python version
+        version_info = sys.version_info
+        current_version = f"{version_info.major}.{version_info.minor}"
+
+        # Parse required version
+        req_parts = required_version.split(".")
+        if len(req_parts) < 2:
+            return False, f"Invalid required version format: {required_version}"
+
+        req_major = int(req_parts[0])
+        req_minor = int(req_parts[1])
+
+        # Compare versions
+        if version_info.major > req_major or (
+            version_info.major == req_major and version_info.minor >= req_minor
+        ):
+            return True, f"Python {current_version} meets requirement >= {required_version}"
+        else:
+            return (
+                False,
+                f"Python {required_version}+ required, found {current_version}",
+            )
+
+    except (ValueError, IndexError) as e:
+        return False, f"Failed to validate Python version: {e}"
+
+
+def validate_windows_path(executable: str) -> tuple[bool, str | None]:
+    """
+    Validate that an executable is in Windows PATH.
+
+    Args:
+        executable: Executable name (e.g., "python", "docker")
+
+    Returns:
+        Tuple of (is_found, path_or_none)
+    """
+    try:
+        # For non-Windows systems, use 'which' or 'where' based on platform
+        if sys.platform.startswith("win"):
+            cmd = ["where", executable]
+        else:
+            cmd = ["which", executable]
+
+        result = subprocess.run(  # noqa: S603
+            cmd,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=5,
+        )
+
+        if result.returncode == 0 and result.stdout.strip():
+            path = result.stdout.strip().split("\n")[0]  # Take first match
+            return True, path
+        else:
+            return False, None
+
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return False, None
+
+
+def validate_pip_available() -> tuple[bool, str]:
+    """
+    Validate that pip is available via python -m pip.
+
+    Returns:
+        Tuple of (is_available, message)
+    """
+    try:
+        result = subprocess.run(  # noqa: S603
+            [sys.executable, "-m", "pip", "--version"],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=10,
+        )
+
+        if result.returncode == 0:
+            version_line = result.stdout.strip()
+            return True, f"pip is available: {version_line}"
+        else:
+            return False, "pip is not available or not working correctly"
+
+    except (subprocess.TimeoutExpired, FileNotFoundError) as e:
+        return False, f"Failed to check pip: {e}"
+
+
+def validate_scoop_format(manifest_path: Path) -> tuple[bool, list[str]]:
+    """
+    Validate Scoop manifest file format and structure.
+
+    Args:
+        manifest_path: Path to Scoop manifest JSON file
+
+    Returns:
+        Tuple of (is_valid, list_of_errors)
+    """
+    import json
+
+    errors: list[str] = []
+
+    # Check file exists
+    if not manifest_path.exists():
+        errors.append(f"Manifest file not found: {manifest_path}")
+        return False, errors
+
+    # Check file is readable
+    try:
+        content = manifest_path.read_text(encoding="utf-8")
+    except Exception as e:
+        errors.append(f"Failed to read manifest: {e}")
+        return False, errors
+
+    # Check valid JSON
+    try:
+        manifest = json.loads(content)
+    except json.JSONDecodeError as e:
+        errors.append(f"Invalid JSON: {e}")
+        return False, errors
+
+    # Validate required fields
+    required_fields = ["version", "description", "homepage", "license", "url", "hash"]
+    for field in required_fields:
+        if field not in manifest:
+            errors.append(f"Missing required field: {field}")
+
+    # Validate version format
+    if "version" in manifest:
+        version = manifest["version"]
+        if not re.match(
+            r"^\d+\.\d+\.\d+(-[a-zA-Z0-9]+(\.[a-zA-Z0-9]+)*)?$",
+            version,
+        ):
+            errors.append(f"Invalid version format: {version}")
+
+    # Validate URL is HTTPS
+    if "url" in manifest:
+        url = manifest["url"]
+        if not url.startswith("https://"):
+            errors.append(f"URL must use HTTPS: {url}")
+
+    # Validate SHA256 format
+    if "hash" in manifest:
+        sha256 = manifest["hash"]
+        if not re.match(r"^[a-fA-F0-9]{64}$", sha256):
+            errors.append(f"Invalid SHA256 format: {sha256}")
+
+    # Validate installer/uninstaller structure
+    if "installer" in manifest and "script" not in manifest["installer"]:
+        errors.append("installer must contain 'script' field")
+
+    if "uninstaller" in manifest and "script" not in manifest["uninstaller"]:
+        errors.append("uninstaller must contain 'script' field")
+
+    return len(errors) == 0, errors
+
+
+def validate_chocolatey_nuspec(nuspec_path: Path) -> tuple[bool, list[str]]:
+    """
+    Validate Chocolatey .nuspec file format and structure.
+
+    Args:
+        nuspec_path: Path to .nuspec XML file
+
+    Returns:
+        Tuple of (is_valid, list_of_errors)
+    """
+    import xml.etree.ElementTree as ET  # nosec B405 - validates local trusted nuspec files
+
+    errors: list[str] = []
+
+    # Check file exists
+    if not nuspec_path.exists():
+        errors.append(f"Nuspec file not found: {nuspec_path}")
+        return False, errors
+
+    # Parse XML
+    try:
+        tree = ET.parse(nuspec_path)  # noqa: S314  # nosec B314 - Local trusted file validation only
+        root = tree.getroot()
+    except ET.ParseError as e:
+        errors.append(f"Invalid XML: {e}")
+        return False, errors
+
+    # Validate required fields (simplified)
+    # Note: Full validation would need to handle XML namespaces
+    required_fields = ["id", "version", "authors", "description"]
+    metadata = root.find("metadata")
+
+    if metadata is None:
+        errors.append("Missing <metadata> element")
+        return False, errors
+
+    for field in required_fields:
+        if metadata.find(field) is None:
+            errors.append(f"Missing required field: {field}")
+
+    return len(errors) == 0, errors

portal/__init__.py

@@ -0,0 +1,19 @@
+"""Kekkai Hosted Portal - DefectDojo-backed multi-tenant security dashboard."""
+
+from __future__ import annotations
+
+__all__ = [
+    "AuthMethod",
+    "AuthResult",
+    "SAMLTenantConfig",
+    "Tenant",
+    "TenantStore",
+    "UploadResult",
+    "authenticate_request",
+    "process_upload",
+    "validate_upload",
+]
+
+from .auth import AuthResult, authenticate_request
+from .tenants import AuthMethod, SAMLTenantConfig, Tenant, TenantStore
+from .uploads import UploadResult, process_upload, validate_upload

portal/api.py

@@ -0,0 +1,155 @@
+"""Portal API endpoints for programmatic access.
+
+Provides REST API endpoints that expose the same data visible in the UI.
+All endpoints require authentication and enforce tenant isolation.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .tenants import Tenant
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class UploadInfo:
+    """Information about an upload."""
+
+    upload_id: str
+    filename: str
+    timestamp: str
+    file_hash: str
+    size_bytes: int
+
+
+@dataclass(frozen=True)
+class TenantStats:
+    """Statistics for a tenant."""
+
+    total_uploads: int
+    total_size_bytes: int
+    last_upload_time: str | None
+
+
+def get_tenant_info(tenant: Tenant) -> dict[str, Any]:
+    """Get tenant information for API response.
+
+    Args:
+        tenant: The authenticated tenant
+
+    Returns:
+        Dictionary containing tenant metadata
+    """
+    return {
+        "id": tenant.id,
+        "name": tenant.name,
+        "dojo_product_id": tenant.dojo_product_id,
+        "dojo_engagement_id": tenant.dojo_engagement_id,
+        "enabled": tenant.enabled,
+        "max_upload_size_mb": tenant.max_upload_size_mb,
+        "auth_method": tenant.auth_method.value,
+        "default_role": tenant.default_role,
+    }
+
+
+def list_uploads(tenant: Tenant, limit: int = 50) -> list[dict[str, Any]]:
+    """List recent uploads for a tenant.
+
+    Args:
+        tenant: The authenticated tenant
+        limit: Maximum number of uploads to return
+
+    Returns:
+        List of upload metadata dictionaries
+    """
+    upload_dir = Path(os.environ.get("PORTAL_UPLOAD_DIR", "/var/lib/kekkai-portal/uploads"))
+    tenant_dir = upload_dir / tenant.id
+
+    if not tenant_dir.exists():
+        return []
+
+    uploads: list[dict[str, Any]] = []
+
+    # Get all upload files for this tenant
+    try:
+        upload_files = sorted(
+            tenant_dir.glob("*.json"),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,
+        )[:limit]
+
+        for upload_file in upload_files:
+            stat = upload_file.stat()
+            uploads.append(
+                {
+                    "upload_id": upload_file.stem,
+                    "filename": upload_file.name,
+                    "timestamp": str(int(stat.st_mtime)),
+                    "size_bytes": stat.st_size,
+                }
+            )
+    except (OSError, PermissionError) as e:
+        logger.warning("Failed to list uploads for tenant %s: %s", tenant.id, e)
+
+    return uploads
+
+
+def get_tenant_stats(tenant: Tenant) -> dict[str, Any]:
+    """Get statistics for a tenant.
+
+    Args:
+        tenant: The authenticated tenant
+
+    Returns:
+        Dictionary containing tenant statistics
+    """
+    upload_dir = Path(os.environ.get("PORTAL_UPLOAD_DIR", "/var/lib/kekkai-portal/uploads"))
+    tenant_dir = upload_dir / tenant.id
+
+    if not tenant_dir.exists():
+        return {
+            "total_uploads": 0,
+            "total_size_bytes": 0,
+            "last_upload_time": None,
+        }
+
+    total_uploads = 0
+    total_size_bytes = 0
+    last_upload_time: int | None = None
+
+    try:
+        for upload_file in tenant_dir.glob("*.json"):
+            stat = upload_file.stat()
+            total_uploads += 1
+            total_size_bytes += stat.st_size
+
+            if last_upload_time is None or stat.st_mtime > last_upload_time:
+                last_upload_time = int(stat.st_mtime)
+
+    except (OSError, PermissionError) as e:
+        logger.warning("Failed to get stats for tenant %s: %s", tenant.id, e)
+
+    return {
+        "total_uploads": total_uploads,
+        "total_size_bytes": total_size_bytes,
+        "last_upload_time": str(last_upload_time) if last_upload_time else None,
+    }
+
+
+def serialize_api_response(data: dict[str, Any]) -> bytes:
+    """Serialize API response to JSON bytes.
+
+    Args:
+        data: Response data dictionary
+
+    Returns:
+        JSON-encoded bytes
+    """
+    return json.dumps(data, indent=2).encode("utf-8")

portal/auth.py

@@ -0,0 +1,103 @@
+"""Authentication middleware for portal API.
+
+Security controls:
+- ASVS V16.3.2: Log failed authorization attempts
+- Constant-time API key comparison to prevent timing attacks
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from kekkai_core import redact
+
+from .tenants import Tenant, TenantStore
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+logger = logging.getLogger(__name__)
+
+BEARER_PATTERN = re.compile(r"^Bearer\s+(\S+)$", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class AuthResult:
+    """Result of authentication attempt."""
+
+    authenticated: bool
+    tenant: Tenant | None = None
+    error: str | None = None
+
+
+def authenticate_request(
+    headers: Mapping[str, str],
+    tenant_store: TenantStore,
+    client_ip: str = "unknown",
+) -> AuthResult:
+    """Authenticate a request using Bearer token.
+
+    Args:
+        headers: Request headers (case-insensitive lookup)
+        tenant_store: Tenant storage for API key verification
+        client_ip: Client IP for logging failed attempts
+
+    Returns:
+        AuthResult with tenant if authenticated, error otherwise
+    """
+    auth_header = _get_header(headers, "Authorization")
+    if not auth_header:
+        _log_auth_failure(client_ip, "missing_header")
+        return AuthResult(authenticated=False, error="Missing Authorization header")
+
+    match = BEARER_PATTERN.match(auth_header)
+    if not match:
+        _log_auth_failure(client_ip, "invalid_format")
+        return AuthResult(authenticated=False, error="Invalid Authorization format")
+
+    api_key = match.group(1)
+    if not api_key:
+        _log_auth_failure(client_ip, "empty_token")
+        return AuthResult(authenticated=False, error="Empty API token")
+
+    tenant = tenant_store.get_by_api_key(api_key)
+    if not tenant:
+        _log_auth_failure(client_ip, "invalid_token", api_key_prefix=api_key[:8])
+        return AuthResult(authenticated=False, error="Invalid API key")
+
+    if not tenant.enabled:
+        _log_auth_failure(client_ip, "tenant_disabled", tenant_id=tenant.id)
+        return AuthResult(authenticated=False, error="Tenant is disabled")
+
+    logger.info(
+        "auth.success client_ip=%s tenant_id=%s",
+        redact(client_ip),
+        tenant.id,
+    )
+    return AuthResult(authenticated=True, tenant=tenant)
+
+
+def _get_header(headers: Mapping[str, str], name: str) -> str | None:
+    """Get header value with case-insensitive lookup."""
+    for key, value in headers.items():
+        if key.lower() == name.lower():
+            return value
+    return None
+
+
+def _log_auth_failure(
+    client_ip: str,
+    reason: str,
+    tenant_id: str | None = None,
+    api_key_prefix: str | None = None,
+) -> None:
+    """Log authentication failure for security monitoring (ASVS V16.3.2)."""
+    parts = [f"auth.failure reason={reason}", f"client_ip={redact(client_ip)}"]
+    if tenant_id:
+        parts.append(f"tenant_id={tenant_id}")
+    if api_key_prefix:
+        parts.append(f"api_key_prefix={api_key_prefix}...")
+    logger.warning(" ".join(parts))

portal/enterprise/__init__.py

@@ -0,0 +1,32 @@
+"""Enterprise features for Kekkai Portal.
+
+Provides:
+- RBAC (Role-Based Access Control)
+- SAML 2.0 SSO integration
+- Audit logging
+- Enterprise license gating
+"""
+
+from __future__ import annotations
+
+from .audit import AuditEvent, AuditEventType, AuditLog
+from .licensing import EnterpriseLicense, LicenseStatus, LicenseValidator
+from .rbac import AuthorizationResult, Permission, RBACManager, Role
+from .saml import SAMLAssertion, SAMLConfig, SAMLError, SAMLProcessor
+
+__all__ = [
+    "AuditEvent",
+    "AuditEventType",
+    "AuditLog",
+    "AuthorizationResult",
+    "EnterpriseLicense",
+    "LicenseStatus",
+    "LicenseValidator",
+    "Permission",
+    "RBACManager",
+    "Role",
+    "SAMLAssertion",
+    "SAMLConfig",
+    "SAMLError",
+    "SAMLProcessor",
+]