diff --git a/API-Reference-Document.md b/API-Reference-Document.md new file mode 100644 index 0000000..ac3b4d8 --- /dev/null +++ b/API-Reference-Document.md @@ -0,0 +1,476 @@ +# Loxide +## API Reference Document + +**Version 1.0 | December 2025** + +--- + +## 1. Overview + +This document provides a complete reference for the AirlockAPIWrapper class and all Airlock API endpoints used by Loxide. + +### 1.1 Authentication + +All API requests require an API key passed via the X-APIKey header: + +``` +Headers: { "X-APIKey": "your-api-key-here" } +``` + +### 1.2 Base URL + +The base URL is configured in `system_config.json` and typically follows the pattern: + +``` +https://airlock.example.com/api +``` + +--- + +## 2. Agent Management + +### 2.1 agent_find_all() + +Retrieve all registered agents. + +**Endpoint:** `POST /v1/agent/find` +**Payload:** `{}` +**Returns:** DataFrame with agent records + +| Field | Type | Description | +|-------|------|-------------| +| `hostname` | str | Device hostname | +| `agentid` | str | Unique identifier | +| `clientversion` | str | Agent version | +| `groupid` | str | Policy group ID | +| `status` | int | 0=Offline, 1=Online, 2=Hidden, 3=Safemode | +| `lastcheckin` | str | Last check-in timestamp | +| `ip` | str | External IP address | +| `localip` | str | Internal IP address | +| `domain` | str | Network domain | +| `os` | str | Operating system | +| `username` | str | Logged-in user | +| `freespace` | int | Available disk space | +| `policyversion` | str | Active policy version | + +### 2.2 agent_find_by_hostname(hostname: str) + +Find agents matching a hostname pattern. + +**Endpoint:** `POST /v1/agent/find` +**Payload:** `{ "hostname": "" }` +**Returns:** DataFrame with matching agents + +### 2.3 agent_find_by_id(agentid: str) + +Find agent by unique ID. + +**Endpoint:** `POST /v1/agent/find` +**Payload:** `{ "agentid": "" }` +**Returns:** DataFrame with agent record + +### 2.4 agent_find_by_status(status: int) + +Find agents by status code. + +**Endpoint:** `POST /v1/agent/find` +**Payload:** `{ "status": }` +**Status Codes:** +- `0` - Offline +- `1` - Online +- `2` - Hidden +- `3` - Safemode + +### 2.5 agent_move(agentid: str, groupid: str) + +Move an agent to a different policy group. + +**Endpoint:** `POST /v1/agent/move` +**Payload:** `{ "agentid": "", "groupid": "" }` +**Returns:** dict with operation result + +### 2.6 agents_find_by_group(groupid: str) + +Find all agents in a policy group. + +**Endpoint:** `POST /v1/agent/find` +**Payload:** `{ "groupid": "" }` +**Returns:** DataFrame with agents + +--- + +## 3. Policy Management + +### 3.1 policy_find_all() + +Retrieve all policy groups. + +**Endpoint:** `POST /v1/group` +**Payload:** `{}` +**Returns:** DataFrame with policy records + +| Field | Type | Description | +|-------|------|-------------| +| `name` | str | Policy display name | +| `groupid` | int | Unique group identifier | +| `hidden` | bool | Visibility flag | +| `parent` | str | Parent policy name (if child) | + +### 3.2 policy_set_auditmode(groupid: str, auditmode: str) + +Toggle policy between audit and enforcement modes. + +**Endpoint:** `POST /v1/group/settings/auditmode` +**Payload:** `{ "groupid": "", "auditmode": "" }` +**Mode Values:** +- `"1"` - Audit mode (log only) +- `"0"` - Enforcement mode (block) + +### 3.3 policy_list_agents(groupid: str) + +List all agents assigned to a policy group. + +**Endpoint:** `POST /v1/group/agents` +**Payload:** `{ "groupid": "" }` +**Returns:** DataFrame with agents + +### 3.4 policy_list_allowlists(groupid: str) + +List allowlists assigned to a policy group. + +**Endpoint:** `POST /v1/group/policies` +**Payload:** `{ "groupid": "" }` +**Returns:** DataFrame with applications + +### 3.5 policy_clone(source_groupid: str, target_groupid: str) + +Clone a policy from one group to another. + +**Endpoint:** `POST /v1/group/assign` +**Payload:** `{ "groupid": "", "targetgroupid": "" }` + +### 3.6 policy_add_path_exclusions(groupid: str, paths: List[str]) + +Add path exclusions to a policy group. + +**Endpoint:** `POST /v1/group/path/add` +**Payload:** `{ "groupid": "", "path": ["", ""] }` + +### 3.7 policy_add_publishers(groupid: str, publishers: List[str]) + +Add trusted publishers to a policy group. + +**Endpoint:** `POST /v1/group/publisher/add` +**Payload:** `{ "groupid": "", "publisher": ["", ""] }` + +--- + +## 4. OTP Management + +### 4.1 otp_generate(agentid: str, duration: int, purpose: str) + +Generate a new One-Time Password for an agent. + +**Endpoint:** `POST /v1/otp/retrieve` +**Payload:** +```json +{ + "agentid": "", + "duration": "", + "purpose": "" +} +``` +**Returns:** str - The generated OTP code + +### 4.2 otp_find_active() + +Retrieve all active OTP sessions. + +**Endpoint:** `POST /v1/otp/usage` +**Payload:** `{ "status": "1" }` +**Returns:** DataFrame with OTP records + +| Field | Type | Description | +|-------|------|-------------| +| `otpid` | str | OTP session identifier | +| `agentid` | str | Associated agent ID | +| `hostname` | str | Agent hostname | +| `purpose` | str | OTP purpose description | +| `granted` | str | Grant timestamp | +| `expires` | str | Expiration timestamp | + +### 4.3 otp_find_awaiting() + +Retrieve OTPs awaiting activation. + +**Endpoint:** `POST /v1/otp/usage` +**Payload:** `{ "status": "0" }` + +### 4.4 otp_find_enforced() + +Retrieve enforced OTPs. + +**Endpoint:** `POST /v1/otp/usage` +**Payload:** `{ "status": "2" }` + +### 4.5 otp_find_revoked() + +Retrieve revoked OTPs. + +**Endpoint:** `POST /v1/otp/usage` +**Payload:** `{ "status": "3" }` + +### 4.6 otp_find_by_agent(agentid: str) + +Retrieve OTPs for a specific agent. + +**Endpoint:** `POST /v1/otp/usage` +**Payload:** `{ "agentid": "" }` + +### 4.7 otp_revoke(otpid: str) + +Revoke an active OTP session. + +**Endpoint:** `POST /v1/otp/revoke` +**Payload:** `{ "otpid": "" }` +**Returns:** dict with operation result + +### 4.8 otp_validate(otpcode: str) + +Validate an OTP code. + +**Endpoint:** `POST /v1/otp/validate` +**Payload:** `{ "otpcode": "" }` +**Returns:** dict indicating validity + +### 4.9 otp_get_activities(otpid: str) + +Retrieve activity log for a specific OTP. + +**Endpoint:** `POST /v1/otp/activities` +**Payload:** `{ "otpid": "" }` +**Returns:** DataFrame with OTP activities + +--- + +## 5. Execution History + +### 5.1 history_execution(today: str, date_selected: str, agent_name: str) + +Retrieve execution history for a specific agent. + +**Endpoint:** `POST /v1/getexechistory` +**Payload:** +```json +{ + "datefrom": "", + "dateto": "", + "hostname": "" +} +``` +**Returns:** List[Dict] with execution records + +| Field | Type | Description | +|-------|------|-------------| +| `type` | int | Execution type code | +| `hostname` | str | Device hostname | +| `username` | str | User who executed | +| `filename` | str | Executed filename | +| `sha256` | str | File hash | +| `publisher` | str | Code signer | +| `datetime` | str | Execution timestamp | +| `policyname` | str | Active policy | +| `policyver` | str | Policy version | +| `commandline` | str | Full command line | +| `pprocess` | str | Parent process | + +### 5.2 Execution Type Codes + +| Code | Description | +|------|-------------| +| 0 | Trusted Execution | +| 1 | Blocked Execution | +| 2 | Untrusted Execution [Audit] | +| 3 | Untrusted Execution [OTP] | +| 4 | Trusted Path Execution | +| 5 | Trusted Publisher Execution | +| 6 | Blocklist Execution | +| 7 | Blocklist Execution [Audit] | +| 8 | Trusted Process Execution | +| 9 | Constrained Execution | +| 10 | Trusted Metadata Execution | +| 11 | Trusted Browser Execution | +| 12 | Blocked Browser Execution | +| 13 | Untrusted Browser Execution [Audit] | +| 14 | Untrusted Browser Execution [OTP] | +| 15 | Blocklist Browser Execution [Audit] | +| 16 | Blocklist Browser Execution | +| 17 | Trusted Installer Execution | +| 18 | Trusted Browser Metadata Execution | + +### 5.3 history_logging(type: List[str], checkpoint: str, policy: Optional[List[str]]) + +Retrieve execution history logs with pagination. + +**Endpoint:** `POST /v1/logging/exechistories` +**Payload:** +```json +{ + "type": ["1", "2", "3"], + "checkpoint": "", + "policy": [""] +} +``` +**Returns:** str with execution histories + +--- + +## 6. Server Logs + +### 6.1 server_logs(checkpoint: Optional[str]) + +Retrieve server activity logs. + +**Endpoint:** `POST /v1/logging/svractivities` +**Payload:** `{}` or `{ "checkpoint": "" }` +**Returns:** str with server activities + +The checkpoint parameter enables pagination for large result sets. Pass the last checkpoint from a previous call to get subsequent records. + +--- + +## 7. Allowlist and Blocklist Management + +### 7.1 allowlist_find_all() + +Retrieve all allowlist applications. + +**Endpoint:** `POST /v1/application` +**Payload:** `{}` +**Returns:** DataFrame with application records + +### 7.2 allowlist_export(applicationid: str) + +Export allowlist as XML. + +**Endpoint:** `POST /v1/application/export` +**Payload:** `{ "applicationid": "" }` +**Returns:** bytes - XML content + +### 7.3 baseline_find_all() + +Retrieve all baselines. + +**Endpoint:** `POST /v1/baseline` +**Payload:** `{}` +**Returns:** DataFrame with baseline records + +### 7.4 baseline_export(baselineid: str) + +Export baseline as XML. + +**Endpoint:** `POST /v1/baseline/export` +**Payload:** `{ "baselineid": "" }` +**Returns:** bytes - XML content + +### 7.5 blocklist_find_all() + +Retrieve all blocklists. + +**Endpoint:** `POST /v1/blocklist` +**Payload:** `{}` +**Returns:** DataFrame with blocklist records + +### 7.6 blocklist_export(blocklistid: str) + +Export blocklist as XML. + +**Endpoint:** `POST /v1/blocklist/export` +**Payload:** `{ "blocklistid": "" }` +**Returns:** bytes - XML content + +### 7.7 hash_add_to_allowlist(applicationid: str, hashes: List[str]) + +Add hashes to an allowlist. + +**Endpoint:** `POST /v1/hash/application/add` +**Payload:** `{ "applicationid": "", "hashes": ["", ...] }` +**Returns:** dict with operation result + +### 7.8 hash_query(hashes: List[str]) + +Query information about specific hashes. + +**Endpoint:** `POST /v1/hash/query` +**Payload:** `{ "hashes": ["", ...] }` +**Returns:** DataFrame with hash records + +| Field | Type | Description | +|-------|------|-------------| +| `sha256` | str | Hash value | +| `filename` | str | Associated filename | +| `publisher` | str | Code signer (or "Not Signed") | +| `reputation` | dict | VirusTotal scan results | +| `applications` | str | Associated allowlists | +| `baselines` | str | Associated baselines | +| `blocklists` | str | Associated blocklists | + +--- + +## 8. Rust Backend (airlock_libs) + +The `airlock_libs` package provides Rust-accelerated functions for performance-critical operations. + +### 8.1 pull_policy_exec_histories(api, type, days, policy_name) + +Pull execution history for policies with optimized performance. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `api` | AirlockAPIWrapper | API wrapper instance | +| `type` | str | JSON list of exec types, e.g., "[1,2,3]" | +| `days` | int | Days to look back | +| `policy_name` | Optional[str] | Specific policy or None for all | + +**Returns:** JSON string with execution history + +### 8.2 history_logging(api, exec_types, checkpoint_number, policy_names) + +Query execution logs with pagination support. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `api` | AirlockAPIWrapper | API wrapper instance | +| `exec_types` | str | JSON list of exec types, e.g., "[3,5,8]" | +| `checkpoint_number` | str | Checkpoint ID for pagination | +| `policy_names` | Optional[str] | Comma-separated policy names or None | + +**Returns:** List[Dict] - Execution history records + +--- + +## 9. Error Handling + +All API methods may raise: + +- `requests.exceptions.RequestException` - Network or HTTP errors +- `ValueError` - Invalid response format +- `KeyError` - Missing expected fields in response + +Recommended pattern: + +```python +try: + result = api.agent_find_all() +except requests.exceptions.RequestException as e: + logger.error(f"API request failed: {e}") + # Handle error appropriately +``` + +--- + +## 10. License + +Copyright (C) 2025 James Brotosky, Brandon Wickline + +GNU Affero General Public License v3.0