Device Agent Guide

If a term is unfamiliar, open the Glossary.

Use the Dralvia device agent when you need host-level header samples (Win/macOS/Linux) for compliance reviews. It only collects metadata and HTTP response headers. No files, keystrokes, or credentials.

Requirements

• Preferred: use published standalone binaries/installers from #/device-agent (no Python required).
• Fallback: Python 3.9+ and requests.
• API key with access to the workspace-scoped Device Activity Signals ingest workflow (same key used for /unified/scan).
• Optional: the Device Activity Signals rollout API shows your agent version coverage.

Downloading the release

Workspace operators can download the signed agent bundle from Workspace Agents & Downloads -> Device Sensor Downloads. The route now opens on an Overview screen, then splits rollout work into Artifacts and Enroll sections so release state, binaries, and host credential generation are easier to scan. The download panel also shows the SHA-256 checksum and exposes checksum/signature files for verification. When available, download the signed Windows installer (.exe) to avoid installing Python on endpoints. The latest update manifest is available from Device Sensor Downloads and the matching API reference entry.

If your workspace uses per-host credentials, open Enroll, enter the hostname on this page, and click Generate credentials. Use the provided key + attestation in the run command below.

Verify integrity (recommended)

sha256sum dralvia-device-agent-<version>.zip

Compare the hash to the SHA-256 value shown in the UI or in the .sha256 file.

If your org publishes a public signing key, verify the signature:

openssl dgst -sha256 -verify dralvia-device-agent-public.pem \
  -signature dralvia-device-agent-<version>.zip.sig \
  dralvia-device-agent-<version>.zip

Running the agent

Windows installer (recommended):

dralvia-device-agent-windows.exe --api-url https://dralvia.tech/api \
  --api-key CHANGE_THIS_TO_YOUR_API_KEY \
  --hostname LAPTOP-001 \
  --enroll \
  --target https://example.com

Linux standalone binary:

chmod +x dralvia-device-agent-linux
./dralvia-device-agent-linux --api-url https://dralvia.tech/api \
  --api-key CHANGE_THIS_TO_YOUR_API_KEY \
  --hostname laptop-001 \
  --enroll \
  --target https://example.com

macOS standalone binary:

chmod +x dralvia-device-agent-macos
./dralvia-device-agent-macos --api-url https://dralvia.tech/api \
  --api-key CHANGE_THIS_TO_YOUR_API_KEY \
  --hostname macbook-001 \
  --enroll \
  --target https://example.com

Python fallback:

python beacon_agent.py --api-url https://dralvia.tech/api/tenant \
  --api-key CHANGE_THIS_TO_YOUR_API_KEY \
  --target https://example.com

Flags:

• --user overrides the username reported to Dralvia (default is the local OS account).
• --target controls which URL the agent fetches to capture response headers.
• --insecure skips TLS verification for dev/self-signed stacks.
• --agent-key supplies a per-host key when your workspace has agent credentials enabled.
• --attestation supplies the attestation token if required by your workspace policy.
• --enroll auto-enrolls the host and fetches credentials using your API key.
• --hostname overrides the detected hostname for enrollment.
• --check-update checks for a newer signed agent release.
• --auto-update downloads the latest release and replaces beacon_agent.py (re-run after update).

After the request completes you should see Capture sent (id=123) and the result will appear inside the Admin HUD at #/device-beacons (requires workspace subscription).

Keeping the agent updated

python beacon_agent.py --api-url https://dralvia.tech/api \
  --api-key CHANGE_THIS_TO_YOUR_API_KEY \
  --check-update

python beacon_agent.py --api-url https://dralvia.tech/api \
  --api-key CHANGE_THIS_TO_YOUR_API_KEY \
  --auto-update \
  --update-pubkey /path/to/dralvia-device-agent-public.pem

If your org provides a public signing key, pass it via --update-pubkey so the agent can verify signatures before updating.

Data collected

• Agent version (reported in metadata).
• Hostname, username, OS name/version, primary IP address.
• Response headers from the target URL (first 50 entries).
• Network metadata (status code, final URL, time to fetch).
• No cookies, DOM contents, or files are transmitted.

Reviewing activity signals

Open the Device Activity Signals workspace in the admin console to see the last 25 captures. Each tile shows host metadata and the sanitized header sample so you can confirm exactly what was collected. Use this during audits to prove the agent is scoped to header posture only. Device activity signals are workspace-scoped, and only your workspace agents are visible in the HUD. You can also check agent rollout coverage from the same workspace flow or its matching API reference entry.

Self-check playbook

Use this 5-step isolation flow before escalating:

1. Configuration: confirm required inputs are present and formatted correctly.
2. Permission: confirm your role can perform the action (401/403 usually indicates authz/authn mismatch).
3. License/feature: confirm the feature is enabled for your workspace plan and module toggles.
4. Quota/rate limit: check for 429 responses and cooldown windows.
5. Service health: if you see 5xx, retry once after 30-60 seconds and capture exact error text.

If still failing, escalate with workspace ID, UTC timestamp, route, action, payload shape (no secrets), and screenshot/error response.

Troubleshooting

Symptom	Fix
Capture failed (401)	Ensure the API key is valid and has access to the workspace-scoped Device Activity Signals ingest workflow.
Beacon failed (403) with host_not_provisioned	Ask your Dralvia admin to provision agent credentials for that hostname.
Beacon failed (403) with agent_key_invalid	Re-check the per-host agent key and header name.
Beacon failed (403) with attestation_stale	Rotate credentials from Device Sensor Downloads and retry with the new attestation.
Beacon failed (403) with agent_revoked	The host credentials are disabled; ask your admin to re-enable or re-provision this host.
SSL: CERTIFICATE_VERIFY_FAILED	Run with --insecure against self-signed dev stacks.
Nothing in HUD	Reload #/device-beacons or confirm the backend is on revision i2j3k4l5m6n7.

Auto-enroll example

python beacon_agent.py --api-url https://dralvia.tech \
  --api-key CHANGE_THIS_TO_YOUR_API_KEY \
  --enroll \
  --target https://example.com

For deployment automation details in workspace context, use the API guidance in this page and contact support if you need rollout templates.

Who this is for

This guide is for workspace owners, workspace admins, and security operators who need clear, repeatable steps without support intervention for day-to-day execution.

Role-based start here

• Workspace Owner: Start with Before you start, then complete Step-by-step and Known limits and rate limits.
• Workspace Admin: Focus on Step-by-step, What each button does, and API and automation.
• Security Analyst: Start at Day-2 operations and Troubleshooting, then use API error quick reference.
• Integrator/Engineer: Start at API and automation, then validate with Step-by-step and FAQ.

Before you start

Use this short checklist before making changes:

1. Confirm you are signed into the correct workspace account.
2. Confirm your role includes the permissions needed for this page.
3. Confirm your browser session is fresh (if pages behave unexpectedly, sign out/in once).
4. Confirm required prerequisites (API keys, agent enrollment, license, upstream integrations) are already in place.

Step-by-step

Follow this sequence for predictable results:

1. Open the workspace from the workspace menu.
2. Review current status/health/last update indicators before making changes.
3. Apply one change at a time and save.
4. Run the available validate/probe/refresh action.
5. Confirm the expected output appears (status change, new event, successful result).
6. If behavior is not as expected, use Troubleshooting below before repeating actions.

Day-2 operations

After initial setup, keep this surface healthy with a simple routine:

1. Daily: verify data freshness and error banners.
2. Weekly: review trends, limits, and failed actions.
3. Monthly: review permissions, keys/tokens, and stale entities.
4. After any incident: capture evidence and update your internal operating notes.

What each button does

Button labels can vary by module, but behavior is consistent:

• Refresh: reloads the latest data from backend APIs without changing configuration.
• Save: persists workspace-scoped configuration changes.
• Run/Probe/Validate: executes a non-destructive health or verification action.
• Download: fetches workspace-scoped artifact(s) (for example bundle, checksum, signature, or report).
• Verify: checks integrity/consistency and returns pass/fail details.
• Enable/Disable: toggles module behavior for your workspace; audit evidence should be recorded.

If a button appears disabled, check role permissions, required fields, and workspace license/feature entitlement first.

API and automation

Everything in this page should remain workspace-scoped. If your team prefers automation, use the corresponding API endpoints with the same guardrails as the UI:

• Use authenticated requests bound to your workspace context.
• Use idempotency/retry controls where available.
• Validate outcomes in the UI after automated runs.

If your endpoint mapping is not obvious, start from Help Center and follow the linked API docs.

Next best actions

After finishing this page, continue with related workflows so your workspace setup stays end-to-end complete:

• EDR response and host actions
• Web Access Protection and dry-run events
• Identity risk and OAuth response
• EvidencePack verification and transparency log
• Risk economics and plan recommendation

FAQ

Q: I clicked save but nothing changed. A: Refresh once, confirm permissions, and verify required fields.

Q: Why do I see missing API key/unauthorized errors? A: Confirm your workspace API key/session is valid and mapped to the correct workspace scope.

Q: Can non-admin users use this page? A: Usually read-only access is possible; write actions require workspace-admin or equivalent roles.

Next steps

After finishing this guide:

1. Validate the result in the related dashboard/workspace.
2. Export or capture evidence if this affects compliance/incident operations.
3. Share the same runbook internally so other operators follow identical steps.
4. Return to Help Center for adjacent workflows.

API error quick reference

Use this matrix when a UI action fails with an HTTP/API error.

Error	Meaning	What to do now
401 Unauthorized	Session token is missing/expired or request is not authenticated.	Sign out/in, refresh once, then retry. Confirm your session is active in the correct workspace.
403 Forbidden	You are authenticated but your role is not allowed to perform this action.	Confirm your role includes the required permission for this button/action. Ask workspace admin to grant access.
404 Not Found	The route/resource does not exist in current workspace context (or feature not enabled).	Confirm URL/route, workspace context, and feature availability. Refresh and retry; if persistent, capture timestamp and route and contact support.
429 Too Many Requests	Rate limit/quota window was exceeded.	Wait for cooldown/reset window, retry once, then reduce burst traffic/backoff if automated.
500 Internal Server Error	Backend failed unexpectedly while processing the request.	Retry after 30-60 seconds. If still failing, escalate with workspace ID, UTC time, route, action, and full error text.

Known limits and rate limits

These limits can vary by plan and feature, but behavior is consistent:

• Burst traffic can trigger 429 Too Many Requests.
• Workspace quotas apply per feature/module and reset on configured windows.
• Repeated retries without backoff can extend recovery time during saturation.

Recommended operator behavior:

1. Retry once after cooldown for 429 responses.
2. Use exponential backoff in automation.
3. Monitor usage/quota dashboards for sustained high utilization.
4. Request quota review when normal workload regularly approaches limits.