AirlockTools/docs/03_API_Reference.md

# 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": "<pattern>" }`  
**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": "<id>" }`  
**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": <code> }`  
**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": "<id>", "groupid": "<target_group>" }`  
**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": "<id>" }`  
**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": "<id>", "auditmode": "<mode>" }`  
**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": "<id>" }`  
**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": "<id>" }`  
**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": "<source>", "targetgroupid": "<target>" }`

### 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": "<id>", "path": ["<path1>", "<path2>"] }`

### 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": "<id>", "publisher": ["<pub1>", "<pub2>"] }`

---

## 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": "<id>",
  "duration": "<minutes>",
  "purpose": "<description>"
}
```
**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": "<id>" }`

### 4.7 otp_revoke(otpid: str)

Revoke an active OTP session.

**Endpoint:** `POST /v1/otp/revoke`  
**Payload:** `{ "otpid": "<id>" }`  
**Returns:** dict with operation result

### 4.8 otp_validate(otpcode: str)

Validate an OTP code.

**Endpoint:** `POST /v1/otp/validate`  
**Payload:** `{ "otpcode": "<code>" }`  
**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": "<id>" }`  
**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": "<YYYY-MM-DD>",
  "dateto": "<YYYY-MM-DD>",
  "hostname": "<name>"
}
```
**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": "<checkpoint_id>",
  "policy": ["<policy_name>"]
}
```
**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": "<last_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": "<id>" }`  
**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": "<id>" }`  
**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": "<id>" }`  
**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": "<id>", "hashes": ["<sha256>", ...] }`  
**Returns:** dict with operation result

### 7.8 hash_query(hashes: List[str])

Query information about specific hashes.

**Endpoint:** `POST /v1/hash/query`  
**Payload:** `{ "hashes": ["<sha256>", ...] }`  
**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