binalyze-air-sdk 1.0.1__py3-none-any.whl

binalyze_air/config.py

@@ -0,0 +1,245 @@
+"""
+Configuration management for the Binalyze AIR SDK.
+"""
+
+import os
+import json
+from typing import Optional, Dict, Any, List
+from pydantic import BaseModel, Field, field_validator
+
+
+class PaginationConfig(BaseModel):
+    """Pagination configuration."""
+    default_page_size: int = Field(default=10, description="Default page size")
+    max_page_size: int = Field(default=100, description="Maximum page size")
+    default_sort_by: str = Field(default="createdAt", description="Default sort field")
+    default_sort_type: str = Field(default="ASC", description="Default sort type")
+
+
+class EndpointConfig(BaseModel):
+    """API endpoint configuration."""
+    acquisitions: Dict[str, str] = Field(default_factory=dict)
+    assets: Dict[str, str] = Field(default_factory=dict)
+    audit: Dict[str, str] = Field(default_factory=dict)
+    auth: Dict[str, str] = Field(default_factory=dict)
+    auto_asset_tags: Dict[str, str] = Field(default_factory=dict)
+    baseline: Dict[str, str] = Field(default_factory=dict)
+    cases: Dict[str, str] = Field(default_factory=dict)
+    policies: Dict[str, str] = Field(default_factory=dict)
+    tasks: Dict[str, str] = Field(default_factory=dict)
+    task_assignments: Dict[str, str] = Field(default_factory=dict)
+    triage_rules: Dict[str, str] = Field(default_factory=dict)
+    organizations: Dict[str, str] = Field(default_factory=dict)
+    users: Dict[str, str] = Field(default_factory=dict)
+    repositories: Dict[str, str] = Field(default_factory=dict)
+
+
+class DefaultFiltersConfig(BaseModel):
+    """Default filter configuration."""
+    organization_ids: List[int] = Field(default=[0])
+    all_organizations: bool = Field(default=True)
+    managed_status: List[str] = Field(default=["managed"])
+    online_status: List[str] = Field(default=["online"])
+    sort_type: str = Field(default="ASC")
+
+
+class TaskDefaultsConfig(BaseModel):
+    """Task default configuration."""
+    cpu_limit: int = Field(default=80)
+    enable_compression: bool = Field(default=True)
+    enable_encryption: bool = Field(default=False)
+    bandwidth_limit: int = Field(default=100000)
+    chunk_size: int = Field(default=1048576)
+    chunk_count: int = Field(default=0)
+    start_offset: int = Field(default=0)
+
+
+class LoggingConfig(BaseModel):
+    """Logging configuration."""
+    level: str = Field(default="INFO")
+    format: str = Field(default="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+    file: str = Field(default="air_sdk.log")
+    max_file_size: str = Field(default="10MB")
+    backup_count: int = Field(default=5)
+
+
+class CacheConfig(BaseModel):
+    """Cache configuration."""
+    enabled: bool = Field(default=True)
+    ttl: int = Field(default=300)
+    max_size: int = Field(default=1000)
+
+
+class RateLimitingConfig(BaseModel):
+    """Rate limiting configuration."""
+    enabled: bool = Field(default=True)
+    requests_per_minute: int = Field(default=100)
+    burst_size: int = Field(default=10)
+
+
+class AIRConfig(BaseModel):
+    """Configuration for the AIR SDK."""
+    
+    host: str = Field(..., description="AIR instance host URL")
+    api_token: str = Field(..., description="API token for authentication")
+    api_prefix: str = Field(default="api/public", description="API prefix path")
+    organization_id: int = Field(default=0, description="Default organization ID")
+    timeout: int = Field(default=30, description="Request timeout in seconds")
+    verify_ssl: bool = Field(default=True, description="Whether to verify SSL certificates")
+    retry_attempts: int = Field(default=3, description="Number of retry attempts for failed requests")
+    retry_delay: float = Field(default=1.0, description="Delay between retry attempts")
+    
+    # Enhanced configuration sections
+    pagination: PaginationConfig = Field(default_factory=PaginationConfig)
+    endpoints: EndpointConfig = Field(default_factory=EndpointConfig)
+    default_filters: DefaultFiltersConfig = Field(default_factory=DefaultFiltersConfig)
+    task_defaults: TaskDefaultsConfig = Field(default_factory=TaskDefaultsConfig)
+    logging: LoggingConfig = Field(default_factory=LoggingConfig)
+    cache: CacheConfig = Field(default_factory=CacheConfig)
+    rate_limiting: RateLimitingConfig = Field(default_factory=RateLimitingConfig)
+    
+    @field_validator("host")
+    @classmethod
+    def validate_host(cls, v):
+        """Ensure host URL is properly formatted."""
+        if not v.startswith(("http://", "https://")):
+            raise ValueError("Host must start with http:// or https://")
+        return v.rstrip("/")
+    
+    @field_validator("api_token")
+    @classmethod
+    def validate_api_token(cls, v):
+        """Ensure API token is not empty."""
+        if not v or not v.strip():
+            raise ValueError("API token cannot be empty")
+        return v.strip()
+    
+    @property
+    def base_url(self) -> str:
+        """Get the full base URL for API requests."""
+        return f"{self.host}/{self.api_prefix}"
+    
+    def get_endpoint(self, category: str, endpoint: str) -> str:
+        """Get a specific endpoint URL."""
+        category_endpoints = getattr(self.endpoints, category, {})
+        if isinstance(category_endpoints, dict):
+            return category_endpoints.get(endpoint, "")
+        return ""
+    
+    def get_full_endpoint_url(self, category: str, endpoint: str, **kwargs) -> str:
+        """Get the full URL for an endpoint with substitutions."""
+        endpoint_path = self.get_endpoint(category, endpoint)
+        if not endpoint_path:
+            raise ValueError(f"Endpoint not found: {category}.{endpoint}")
+        
+        # Substitute path parameters
+        full_path = endpoint_path.format(**kwargs)
+        return f"{self.base_url}{full_path}"
+    
+    @classmethod
+    def from_environment(cls) -> "AIRConfig":
+        """Create configuration from environment variables."""
+        config_data = {
+            "host": os.getenv("AIR_HOST", ""),
+            "api_token": os.getenv("AIR_API_TOKEN", ""),
+            "api_prefix": os.getenv("AIR_API_PREFIX", "api/public"),
+            "organization_id": int(os.getenv("AIR_ORGANIZATION_ID", "0")),
+            "timeout": int(os.getenv("AIR_TIMEOUT", "30")),
+            "verify_ssl": os.getenv("AIR_VERIFY_SSL", "true").lower() == "true",
+            "retry_attempts": int(os.getenv("AIR_RETRY_ATTEMPTS", "3")),
+            "retry_delay": float(os.getenv("AIR_RETRY_DELAY", "1.0")),
+        }
+        
+        return cls(**config_data)
+    
+    @classmethod
+    def from_file(cls, config_path: str = "config.json") -> "AIRConfig":
+        """Create configuration from JSON file."""
+        try:
+            with open(config_path, "r") as f:
+                config_data = json.load(f)
+            return cls(**config_data)
+        except FileNotFoundError:
+            raise FileNotFoundError(f"Configuration file not found: {config_path}")
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON in configuration file: {e}")
+    
+    @classmethod
+    def create(
+        cls,
+        host: Optional[str] = None,
+        api_token: Optional[str] = None,
+        organization_id: Optional[int] = None,
+        config_file: Optional[str] = None,
+        **kwargs
+    ) -> "AIRConfig":
+        """Create configuration with precedence: params > env vars > config file."""
+        config_data = {}
+        
+        # 1. Try config file first (lowest precedence)
+        if config_file and os.path.exists(config_file):
+            try:
+                with open(config_file, "r") as f:
+                    config_data = json.load(f)
+            except (json.JSONDecodeError, IOError):
+                pass  # Ignore file errors, will try other methods
+        elif os.path.exists("config.json"):
+            # Try default config.json
+            try:
+                with open("config.json", "r") as f:
+                    config_data = json.load(f)
+            except (json.JSONDecodeError, IOError):
+                pass
+        
+        # 2. Override with environment variables
+        env_config = {}
+        if os.getenv("AIR_HOST"):
+            env_config["host"] = os.getenv("AIR_HOST")
+        if os.getenv("AIR_API_TOKEN"):
+            env_config["api_token"] = os.getenv("AIR_API_TOKEN")
+        if os.getenv("AIR_API_PREFIX"):
+            env_config["api_prefix"] = os.getenv("AIR_API_PREFIX")
+        
+        org_id_env = os.getenv("AIR_ORGANIZATION_ID")
+        if org_id_env:
+            env_config["organization_id"] = int(org_id_env)
+            
+        timeout_env = os.getenv("AIR_TIMEOUT")
+        if timeout_env:
+            env_config["timeout"] = int(timeout_env)
+            
+        verify_ssl_env = os.getenv("AIR_VERIFY_SSL")
+        if verify_ssl_env:
+            env_config["verify_ssl"] = verify_ssl_env.lower() == "true"
+            
+        retry_attempts_env = os.getenv("AIR_RETRY_ATTEMPTS")
+        if retry_attempts_env:
+            env_config["retry_attempts"] = int(retry_attempts_env)
+            
+        retry_delay_env = os.getenv("AIR_RETRY_DELAY")
+        if retry_delay_env:
+            env_config["retry_delay"] = float(retry_delay_env)
+        
+        config_data.update(env_config)
+        
+        # 3. Override with explicit parameters (highest precedence)
+        if host is not None:
+            config_data["host"] = host
+        if api_token is not None:
+            config_data["api_token"] = api_token
+        if organization_id is not None:
+            config_data["organization_id"] = organization_id
+        
+        # Add any additional kwargs
+        config_data.update(kwargs)
+        
+        return cls(**config_data)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert configuration to dictionary."""
+        return self.model_dump()
+    
+    def save_to_file(self, config_path: str = "config.json") -> None:
+        """Save configuration to JSON file."""
+        with open(config_path, "w") as f:
+            json.dump(self.to_dict(), f, indent=2) 

binalyze_air/exceptions.py

@@ -0,0 +1,50 @@
+"""
+Custom exceptions for the Binalyze AIR SDK.
+"""
+
+from typing import Optional, Dict, Any
+
+
+class AIRAPIError(Exception):
+    """Base exception for all AIR API errors."""
+    
+    def __init__(self, message: str, status_code: Optional[int] = None, response_data: Optional[Dict[str, Any]] = None):
+        self.message = message
+        self.status_code = status_code
+        self.response_data = response_data or {}
+        super().__init__(self.message)
+
+
+class AuthenticationError(AIRAPIError):
+    """Raised when authentication fails."""
+    pass
+
+
+class AuthorizationError(AIRAPIError):
+    """Raised when authorization fails."""
+    pass
+
+
+class NotFoundError(AIRAPIError):
+    """Raised when a resource is not found."""
+    pass
+
+
+class ValidationError(AIRAPIError):
+    """Raised when request validation fails."""
+    pass
+
+
+class RateLimitError(AIRAPIError):
+    """Raised when rate limit is exceeded."""
+    pass
+
+
+class ServerError(AIRAPIError):
+    """Raised when server returns 5xx status codes."""
+    pass
+
+
+class NetworkError(AIRAPIError):
+    """Raised when network-related errors occur."""
+    pass 

binalyze_air/http_client.py

@@ -0,0 +1,306 @@
+"""
+HTTP client for Binalyze AIR API communications.
+"""
+
+import time
+import requests
+import urllib3
+from typing import Any, Dict, Optional, Union
+from urllib.parse import urljoin
+
+from .config import AIRConfig
+from .exceptions import (
+    AIRAPIError,
+    AuthenticationError,
+    AuthorizationError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+    ServerError,
+    NetworkError,
+)
+
+
+class HTTPClient:
+    """HTTP client for AIR API communications."""
+    
+    def __init__(self, config: AIRConfig):
+        """Initialize the HTTP client with configuration."""
+        self.config = config
+        self.session = requests.Session()
+        self.session.headers.update({
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {config.api_token}",
+            "User-Agent": "binalyze-air-sdk/1.0.0",
+        })
+        self.session.verify = config.verify_ssl
+        
+        # Disable SSL warnings when SSL verification is disabled
+        if not config.verify_ssl:
+            urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+    
+    def _build_url(self, endpoint: str) -> str:
+        """Build full URL from endpoint."""
+        # Remove leading slash if present
+        endpoint = endpoint.lstrip("/")
+        # Build full URL with API prefix
+        return f"{self.config.host}/{self.config.api_prefix}/{endpoint}"
+    
+    def _handle_response(self, response: requests.Response) -> Dict[str, Any]:
+        """Handle HTTP response and raise appropriate exceptions."""
+        try:
+            data = response.json()
+        except ValueError:
+            # If response is not JSON, create a basic structure
+            data = {
+                "success": False,
+                "result": None,
+                "statusCode": response.status_code,
+                "errors": [response.text or "Unknown error"]
+            }
+        
+        # Handle specific known API bugs with better error messages
+        if response.status_code == 500:
+            error_message = data.get("errors", [""])[0] if data.get("errors") else ""
+            
+            # API-001: Policies endpoint parameter validation bug
+            if "GET: /api/public/policies route has internal server error" in error_message:
+                raise ValidationError(
+                    "Missing required 'organizationIds' filter parameter. "
+                    "Please provide organization IDs to filter policies. "
+                    "(Note: This is a known API server bug that returns 500 instead of 400)",
+                    status_code=400,  # What it should be
+                    response_data=data
+                )
+            
+            # API-002: Auto asset tags update endpoint bug  
+            if "auto-asset-tag" in response.url and response.request.method == "PUT":
+                raise ServerError(
+                    "Auto asset tag update is currently unavailable due to a server bug. "
+                    "Workaround: Delete the existing tag and create a new one with updated values. "
+                    "(Note: This is a known API server issue)",
+                    status_code=response.status_code,
+                    response_data=data
+                )
+        
+        # Check for specific error status codes
+        if response.status_code == 401:
+            raise AuthenticationError(
+                "Authentication failed. Check your API token.",
+                status_code=response.status_code,
+                response_data=data
+            )
+        elif response.status_code == 403:
+            raise AuthorizationError(
+                "Authorization failed. Insufficient permissions.",
+                status_code=response.status_code,
+                response_data=data
+            )
+        elif response.status_code == 404:
+            # Use specific API error message instead of generic message
+            api_errors = data.get("errors", ["Resource not found"])
+            error_message = "; ".join(api_errors) if api_errors else "Resource not found"
+            raise NotFoundError(
+                error_message,
+                status_code=response.status_code,
+                response_data=data
+            )
+        elif response.status_code == 422:
+            errors = data.get("errors", ["Validation failed"])
+            raise ValidationError(
+                f"Validation error: {'; '.join(errors)}",
+                status_code=response.status_code,
+                response_data=data
+            )
+        elif response.status_code == 429:
+            raise RateLimitError(
+                "Rate limit exceeded. Please try again later.",
+                status_code=response.status_code,
+                response_data=data
+            )
+        elif response.status_code >= 500:
+            raise ServerError(
+                f"Server error: {response.status_code}",
+                status_code=response.status_code,
+                response_data=data
+            )
+        elif not response.ok:
+            errors = data.get("errors", [f"HTTP {response.status_code}"])
+            raise AIRAPIError(
+                f"API error: {'; '.join(errors)}",
+                status_code=response.status_code,
+                response_data=data
+            )
+        
+        return data
+    
+    def _handle_binary_response(self, response: requests.Response) -> requests.Response:
+        """Handle binary file response without JSON parsing."""
+        # Check for specific error status codes
+        if response.status_code == 401:
+            raise AuthenticationError(
+                "Authentication failed. Check your API token.",
+                status_code=response.status_code
+            )
+        elif response.status_code == 403:
+            raise AuthorizationError(
+                "Authorization failed. Insufficient permissions.",
+                status_code=response.status_code
+            )
+        elif response.status_code == 404:
+            raise NotFoundError(
+                "Resource not found.",
+                status_code=response.status_code
+            )
+        elif response.status_code == 422:
+            raise ValidationError(
+                "Validation error",
+                status_code=response.status_code
+            )
+        elif response.status_code == 429:
+            raise RateLimitError(
+                "Rate limit exceeded. Please try again later.",
+                status_code=response.status_code
+            )
+        elif response.status_code >= 500:
+            raise ServerError(
+                f"Server error: {response.status_code}",
+                status_code=response.status_code
+            )
+        elif not response.ok:
+            raise AIRAPIError(
+                f"API error: HTTP {response.status_code}",
+                status_code=response.status_code
+            )
+        
+        return response
+    
+    def _make_request(
+        self,
+        method: str,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        json_data: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Make HTTP request with retry logic."""
+        url = self._build_url(endpoint)
+        last_exception = None
+        
+        for attempt in range(self.config.retry_attempts):
+            try:
+                response = self.session.request(
+                    method=method,
+                    url=url,
+                    params=params,
+                    data=data,
+                    json=json_data,
+                    timeout=self.config.timeout
+                )
+                return self._handle_response(response)
+                
+            except (requests.ConnectionError, requests.Timeout) as e:
+                last_exception = NetworkError(f"Network error: {str(e)}")
+                if attempt < self.config.retry_attempts - 1:
+                    time.sleep(self.config.retry_delay * (2 ** attempt))  # Exponential backoff
+                    continue
+                raise last_exception
+            
+            except (RateLimitError, ServerError) as e:
+                last_exception = e
+                if attempt < self.config.retry_attempts - 1:
+                    time.sleep(self.config.retry_delay * (2 ** attempt))
+                    continue
+                raise
+            
+            except (AuthenticationError, AuthorizationError, NotFoundError, ValidationError) as e:
+                # Don't retry these errors
+                raise
+        
+        # If we get here, all retries failed
+        if last_exception:
+            raise last_exception
+        
+        raise AIRAPIError("All retry attempts failed")
+    
+    def get(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Make GET request."""
+        return self._make_request("GET", endpoint, params=params)
+    
+    def post(
+        self,
+        endpoint: str,
+        data: Optional[Dict[str, Any]] = None,
+        json_data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Make POST request."""
+        return self._make_request("POST", endpoint, params=params, data=data, json_data=json_data)
+    
+    def put(
+        self,
+        endpoint: str,
+        data: Optional[Dict[str, Any]] = None,
+        json_data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Make PUT request."""
+        return self._make_request("PUT", endpoint, params=params, data=data, json_data=json_data)
+    
+    def patch(
+        self,
+        endpoint: str,
+        data: Optional[Dict[str, Any]] = None,
+        json_data: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Make PATCH request."""
+        return self._make_request("PATCH", endpoint, params=params, data=data, json_data=json_data)
+    
+    def delete(
+        self, 
+        endpoint: str, 
+        params: Optional[Dict[str, Any]] = None,
+        json_data: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Make DELETE request."""
+        return self._make_request("DELETE", endpoint, params=params, json_data=json_data)
+    
+    def get_binary(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> requests.Response:
+        """Make GET request for binary file downloads."""
+        url = self._build_url(endpoint)
+        last_exception = None
+        
+        for attempt in range(self.config.retry_attempts):
+            try:
+                response = self.session.request(
+                    method="GET",
+                    url=url,
+                    params=params,
+                    timeout=self.config.timeout
+                )
+                return self._handle_binary_response(response)
+                
+            except (requests.ConnectionError, requests.Timeout) as e:
+                last_exception = NetworkError(f"Network error: {str(e)}")
+                if attempt < self.config.retry_attempts - 1:
+                    time.sleep(self.config.retry_delay * (2 ** attempt))  # Exponential backoff
+                    continue
+                raise last_exception
+            
+            except (RateLimitError, ServerError) as e:
+                last_exception = e
+                if attempt < self.config.retry_attempts - 1:
+                    time.sleep(self.config.retry_delay * (2 ** attempt))
+                    continue
+                raise
+            
+            except (AuthenticationError, AuthorizationError, NotFoundError, ValidationError) as e:
+                # Don't retry these errors
+                raise
+        
+        # If we get here, all retries failed
+        if last_exception:
+            raise last_exception
+        
+        raise AIRAPIError("All retry attempts failed")