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:

{
  "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:

{
  "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:

{
  "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:

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