Security Guard

Implementation

Protection

Path Traversal Jail

os.path.realpath canonicalization inside /config

Prevents access to /etc/shadow, root system files, or container host escape (403 Forbidden).

Constant-Time Auth

hmac.compare_digest for X-Addon-API-Key

Eliminates timing-attack vulnerabilities against app API authentication.

Deny-List Protection

File path blocking on secrets.yaml, .storage/core.auth, *.pem, SSH keys

Protects sensitive user credentials and tokens from being read or overwritten.

Secret Redaction

Regex redaction filters on log streaming

Automatically sanitizes passwords, long-lived tokens, and API keys from tail logs.

Atomic Pre-Edit Snapshots

Automated .snapshots/ creation before writes

Guarantees safe rollback to the exact prior disk state upon syntax or runtime errors.

Role-Based Access Control

Ephemeral token issuance with strict policy bounds (ha_agent_list_policies)

Restricts AI subagents to explicit tool, file, and service boundaries, limiting blast radius.

Audit Logging Service

Append-only JSONL event logging across API endpoints (ha_audit_get_logs)

Provides immutable, queryable records of all AI actions, blocked attempts, and operational rationale.

Tool Name

Parameters

Description

ha_dashboard_get_config

dashboard_slug?

Retrieve Lovelace dashboard configuration via WebSocket or storage file.

ha_dashboard_save_config

config_yaml, dashboard_slug?, label?

Validate YAML schema, trigger automatic safety snapshot, and commit dashboard updates.

ha_dashboard_render_screenshot

url_path, device_preset?, dark_mode?, element_selector?

Render high-resolution PNG screenshot via Playwright (presets: desktop, tablet, mobile).

Tool Name

Parameters

Description

ha_automation_list

domain? (automation, script, scene)

List active automations/scripts with entity IDs, friendly names, and trigger times.

ha_automation_read

automation_id

Fetch the exact YAML definition of a specific automation or script.

ha_automation_write

automation_id, yaml_code, label?

Validate YAML syntax, snapshot file, update automation block, and trigger service reload.

ha_automation_trigger

entity_id

Manually trigger an automation or script entity to verify execution.

Tool Name

Parameters

Description

ha_system_health

(none)

Check health and connectivity of both Home Assistant Core and the App daemon.

ha_system_list_entities

domain_filter?, search_query?

Search and filter entities by domain (e.g. light, sensor, climate) with full attributes.

ha_system_call_service

domain, service, service_data?

Invoke any Home Assistant domain service (e.g. light.turn_on, switch.toggle, climate.set_temperature).

ha_system_get_logs

lines_count? (default: 100)

Retrieve the last $N$ lines of Home Assistant core logs with automatic secret redaction.

ha_system_create_backup

label

Create a named manual snapshot backup in /config/.snapshots/.

ha_system_restore_backup

snapshot_id

Atomically restore a file from a snapshot ID with safety backup preservation.

Tool Name

Parameters

Description

ha_audit_get_logs

agent_id?, role?, status?, limit?, since?, rationale?

Query immutable JSONL audit logs for security, troubleshooting, and compliance filtering by agent, role, or status.

ha_agent_issue_token

agent_id, role, ttl_minutes?, rationale?

Issue a short-lived ephemeral token dynamically scoped to specific RBAC role boundaries (default 60m TTL).

ha_agent_list_policies

(none)

Retrieve all active RBAC agent roles, their tool permissions, path restrictions, and service whitelists.