pyattackforge 0.0.1__py3-none-any.whl

pyattackforge/__init__.py

@@ -0,0 +1,5 @@
+"""PyAttackForge SDK."""
+
+from .client import AttackForgeClient
+
+__all__ = ["AttackForgeClient"]

pyattackforge/cache.py

@@ -0,0 +1,33 @@
+"""Small TTL cache used by the SDK to reduce API calls."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+import time
+
+
+@dataclass
+class CacheEntry:
+    value: Any
+    expires_at: float
+
+
+class TTLCache:
+    def __init__(self, default_ttl: float = 300.0) -> None:
+        self._default_ttl = default_ttl
+        self._data: Dict[str, CacheEntry] = {}
+
+    def get(self, key: str) -> Optional[Any]:
+        entry = self._data.get(key)
+        if not entry:
+            return None
+        if entry.expires_at < time.monotonic():
+            self._data.pop(key, None)
+            return None
+        return entry.value
+
+    def set(self, key: str, value: Any, ttl: Optional[float] = None) -> None:
+        ttl_value = self._default_ttl if ttl is None else ttl
+        self._data[key] = CacheEntry(value=value, expires_at=time.monotonic() + ttl_value)
+
+    def clear(self) -> None:
+        self._data.clear()

pyattackforge/client.py

@@ -0,0 +1,155 @@
+"""High-level AttackForge client."""
+
+from __future__ import annotations
+
+from typing import Optional, Sequence, Dict, Any
+import time
+
+from .config import ClientConfig, config_from_env
+from .exceptions import APIError
+from .transport import AttackForgeTransport
+from .resources import (
+    AssetsResource,
+    ProjectsResource,
+    FindingsResource,
+    WriteupsResource,
+    TestcasesResource,
+    TestsuitesResource,
+    NotesResource,
+    UsersResource,
+    ReportsResource,
+)
+
+
+class AttackForgeClient:
+    """Facade client exposing resource groups for the AttackForge SSAPI."""
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        config: Optional[ClientConfig] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        backoff_factor: Optional[float] = None,
+        http2: Optional[bool] = None,
+    ) -> None:
+        if config is None:
+            if base_url and api_key:
+                config = ClientConfig(
+                    base_url=base_url,
+                    api_key=api_key,
+                    timeout=30.0 if timeout is None else timeout,
+                    max_retries=3 if max_retries is None else max_retries,
+                    backoff_factor=0.5 if backoff_factor is None else backoff_factor,
+                    http2=True if http2 is None else http2,
+                )
+            else:
+                config = config_from_env()
+        self._transport = AttackForgeTransport(config)
+
+        self.assets = AssetsResource(self._transport)
+        self.projects = ProjectsResource(self._transport)
+        self.findings = FindingsResource(self._transport)
+        self.writeups = WriteupsResource(self._transport)
+        self.testcases = TestcasesResource(self._transport)
+        self.testsuites = TestsuitesResource(self._transport)
+        self.notes = NotesResource(self._transport)
+        self.users = UsersResource(self._transport)
+        self.reports = ReportsResource(self._transport)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> "AttackForgeClient":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def link_vulnerability_to_testcases(
+        self,
+        project_id: str,
+        vulnerability_id: str,
+        testcase_ids: Sequence[str],
+        *,
+        verify: bool = True,
+        attempts: int = 3,
+        delay: float = 1.0,
+    ) -> Dict[str, Any]:
+        """
+        Link a vulnerability to project testcases, updating both sides (vulnerability + testcase).
+
+        Best-effort: errors on either side do not raise by default. Returns linkage metadata.
+        """
+        candidates = [value for value in testcase_ids if value]
+        if not candidates:
+            return {"action": "noop", "linked_testcases": []}
+
+        linked_testcases = set()
+        try:
+            vuln = self.findings.get_vulnerability(vulnerability_id)
+            linked_testcases = self.findings.extract_linked_testcase_ids(vuln)
+        except APIError:
+            linked_testcases = set()
+
+        updated = sorted(linked_testcases.union(candidates))
+        if set(updated) != linked_testcases:
+            payload = {"linked_testcases": updated, "projectId": project_id}
+            try:
+                self.findings.update_vulnerability(vulnerability_id, payload)
+            except APIError:
+                pass
+
+        for testcase_id in candidates:
+            try:
+                testcases_data = self.testcases.get_project_testcases(project_id)
+            except APIError:
+                continue
+            testcase = self.testcases.find_project_testcase_entry(testcases_data, testcase_id)
+            if not testcase:
+                continue
+            existing = self.testcases.extract_linked_vulnerability_ids(testcase)
+            if vulnerability_id in existing:
+                continue
+            payload = {"linked_vulnerabilities": sorted(existing.union({vulnerability_id}))}
+            try:
+                self.testcases.update_testcase(project_id, testcase_id, payload)
+            except APIError:
+                pass
+
+        if not verify:
+            return {"linked_testcases": updated, "verified": False}
+
+        verified = False
+        for _ in range(max(attempts, 1)):
+            try:
+                vuln = self.findings.get_vulnerability(vulnerability_id)
+                linked_testcases = self.findings.extract_linked_testcase_ids(vuln)
+            except APIError:
+                linked_testcases = set()
+            missing = [tc_id for tc_id in candidates if tc_id not in linked_testcases]
+            if missing:
+                time.sleep(delay)
+                continue
+            try:
+                testcases_data = self.testcases.get_project_testcases(project_id)
+            except APIError:
+                time.sleep(delay)
+                continue
+            ok = True
+            for tc_id in candidates:
+                testcase = self.testcases.find_project_testcase_entry(testcases_data, tc_id)
+                if not testcase:
+                    ok = False
+                    break
+                linked_vulns = self.testcases.extract_linked_vulnerability_ids(testcase)
+                if vulnerability_id not in linked_vulns:
+                    ok = False
+                    break
+            if ok:
+                verified = True
+                break
+            time.sleep(delay)
+        return {"linked_testcases": updated, "verified": verified}

pyattackforge/config.py

@@ -0,0 +1,61 @@
+"""Configuration helpers."""
+
+from dataclasses import dataclass
+import os
+from typing import Optional
+
+from .exceptions import ConfigError
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    base_url: str
+    api_key: str
+    ui_base_url: Optional[str] = None
+    ui_token: Optional[str] = None
+    timeout: float = 30.0
+    max_retries: int = 3
+    backoff_factor: float = 0.5
+    user_agent: str = "pyattackforge/0.0.1"
+    http2: bool = True
+    # Default visibility for newly created findings. False = pending/hidden.
+    default_findings_visible: bool = False
+    # Default substatus custom field for newly created findings.
+    default_findings_substatus_key: Optional[str] = "substatus"
+    default_findings_substatus_value: Optional[str] = "Observed"
+
+
+def config_from_env() -> ClientConfig:
+    base_url = os.getenv("ATTACKFORGE_BASE_URL")
+    api_key = os.getenv("ATTACKFORGE_API_KEY")
+    if not base_url or not api_key:
+        raise ConfigError("ATTACKFORGE_BASE_URL and ATTACKFORGE_API_KEY are required")
+    ui_base_url = os.getenv("ATTACKFORGE_UI_BASE_URL")
+    ui_token = os.getenv("ATTACKFORGE_UI_TOKEN")
+    visible_env = os.getenv("ATTACKFORGE_FINDINGS_VISIBLE_DEFAULT")
+    substatus_key_env = os.getenv("ATTACKFORGE_FINDINGS_SUBSTATUS_KEY")
+    substatus_value_env = os.getenv("ATTACKFORGE_FINDINGS_SUBSTATUS_VALUE")
+    default_visible = False
+    if visible_env is not None:
+        default_visible = visible_env.strip().lower() in {"1", "true", "yes", "y", "visible"}
+    return ClientConfig(
+        base_url=base_url,
+        api_key=api_key,
+        ui_base_url=ui_base_url,
+        ui_token=ui_token,
+        default_findings_visible=default_visible,
+        default_findings_substatus_key=_normalize_default_substatus(substatus_key_env, "substatus"),
+        default_findings_substatus_value=_normalize_default_substatus(substatus_value_env, "Observed"),
+    )
+
+
+def _normalize_default_substatus(value: Optional[str], default: str) -> Optional[str]:
+    if value is None:
+        return default
+    cleaned = value.strip()
+    if not cleaned:
+        return None
+    lowered = cleaned.lower()
+    if lowered in {"none", "null", "false", "0", "off", "disable", "disabled"}:
+        return None
+    return cleaned

pyattackforge/exceptions.py

@@ -0,0 +1,21 @@
+"""SDK exception types."""
+
+from typing import Optional
+
+
+class AttackForgeError(Exception):
+    """Base exception for SDK errors."""
+
+
+class ConfigError(AttackForgeError):
+    """Raised when required configuration is missing or invalid."""
+
+
+class APIError(AttackForgeError):
+    """Raised for non-successful HTTP responses."""
+
+    def __init__(self, status_code: int, message: str, payload: Optional[dict] = None) -> None:
+        super().__init__(f"HTTP {status_code}: {message}")
+        self.status_code = status_code
+        self.message = message
+        self.payload = payload or {}

pyattackforge/resources/__init__.py

@@ -0,0 +1,23 @@
+"""Resource modules."""
+
+from .assets import AssetsResource
+from .projects import ProjectsResource
+from .findings import FindingsResource
+from .writeups import WriteupsResource
+from .testcases import TestcasesResource
+from .testsuites import TestsuitesResource
+from .notes import NotesResource
+from .users import UsersResource
+from .reports import ReportsResource
+
+__all__ = [
+    "AssetsResource",
+    "ProjectsResource",
+    "FindingsResource",
+    "WriteupsResource",
+    "TestcasesResource",
+    "TestsuitesResource",
+    "NotesResource",
+    "UsersResource",
+    "ReportsResource",
+]

pyattackforge/resources/assets.py

@@ -0,0 +1,39 @@
+"""Resource: assets."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from ..cache import TTLCache
+from .base import BaseResource
+
+
+class AssetsResource(BaseResource):
+    """Assets API resource wrapper."""
+
+    def __init__(self, transport) -> None:  # type: ignore[override]
+        super().__init__(transport)
+        self._cache = TTLCache(default_ttl=300.0)
+
+    def create_asset_in_library(self, payload: Dict[str, Any]) -> Any:
+        return self._post("/api/ss/library/asset", json=payload)
+
+    def update_asset_in_library(self, asset_id: str, payload: Dict[str, Any]) -> Any:
+        return self._put(f"/api/ss/library/asset/{asset_id}", json=payload)
+
+    def get_assets(self, params: Optional[Dict[str, Any]] = None, *, force_refresh: bool = False) -> Any:
+        cache_key = "assets:list"
+        if params is None and not force_refresh:
+            cached = self._cache.get(cache_key)
+            if cached is not None:
+                return cached
+        data = self._get("/api/ss/assets", params=params)
+        if params is None:
+            self._cache.set(cache_key, data)
+        return data
+
+    def get_asset_in_library(self, asset_id: str) -> Any:
+        return self._get("/api/ss/library/asset", params={"id": asset_id})
+
+    def get_asset_library_assets(self, payload: Dict[str, Any]) -> Any:
+        return self._post("/api/ss/library/assets", json=payload)

pyattackforge/resources/base.py

@@ -0,0 +1,33 @@
+"""Base resource helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from ..transport import AttackForgeTransport
+
+
+class BaseResource:
+    def __init__(self, transport: AttackForgeTransport) -> None:
+        self._transport = transport
+
+    def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        return self._transport.request("GET", path, params=params).data
+
+    def _post(self, path: str, json: Optional[Dict[str, Any]] = None, params: Optional[Dict[str, Any]] = None) -> Any:
+        return self._transport.request("POST", path, json=json, params=params).data
+
+    def _put(self, path: str, json: Optional[Dict[str, Any]] = None, params: Optional[Dict[str, Any]] = None) -> Any:
+        return self._transport.request("PUT", path, json=json, params=params).data
+
+    def _delete(
+        self,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        return self._transport.request("DELETE", path, params=params, json=json).data
+
+    def _post_files(self, path: str, files: Dict[str, Any], params: Optional[Dict[str, Any]] = None) -> Any:
+        return self._transport.request("POST", path, files=files, params=params).data