Agent Management

The Agents page provides centralized management of all Tamandua Sentinel agents deployed across your environment. This guide covers agent viewing, grouping, monitoring, and lifecycle management.

Accessing Agent Management

Navigate to Agents in the left navigation panel to access the agent management interface.

[Screenshot: Agents page with list view and action toolbar]

Agent List View

List Columns

The agent list displays the following information by default:

Customizing Columns

Add or remove columns:

1. Click the Columns button in the toolbar
2. Check/uncheck desired columns
3. Drag to reorder columns
4. Click Apply

[Screenshot: Column customization dropdown with available fields]

Additional available columns:

• External IP
• MAC Address
• Domain
• Tags
• First Seen
• Serial Number
• Memory Usage
• CPU Usage
• Disk Usage
• Detection Rules Version

Sorting

Click any column header to sort:

• First click: Ascending (A-Z, oldest first)
• Second click: Descending (Z-A, newest first)
• Third click: Clear sort

Multi-column sort: Hold Shift while clicking additional columns.

Filtering

Quick Filters

Use the quick filter bar for common filters:

[Screenshot: Quick filter bar with multiple filters applied]

Advanced Filters

Click Advanced for complex queries:

hostname contains "server" AND
os_type = "windows" AND
last_seen > "24h ago" AND
alert_count > 0

Search

Use the search box for text-based search across:

• Hostname
• IP address
• Tags
• Username

Pagination

Configure items per page: 25, 50, 100, 250

Navigate pages using the pagination controls or keyboard:

• Right Arrow: Next page
• Left Arrow: Previous page

Agent Details

Click any agent row to open the agent detail panel.

[Screenshot: Agent detail panel showing all sections]

Overview Tab

Primary agent information:

System Information Tab

Detailed system specifications:

• Hardware: CPU, memory, disk
• Network: All interfaces with configuration
• Software: Installed applications
• Services: Running services
• Startup Items: Auto-start programs
• Certificates: Installed certificates

Agent Health Tab

Agent component status:

Timeline Tab

Chronological view of agent activity:

[2024-01-15 14:32:00] Agent check-in
[2024-01-15 14:30:45] Configuration updated
[2024-01-15 14:25:12] Alert triggered: Suspicious PowerShell
[2024-01-15 14:00:00] Detection rules updated
[2024-01-15 10:30:00] Agent started

Alerts Tab

Open alerts for this agent:

Response History Tab

Commands executed on this agent:

Agent Groups

Groups organize agents for policy application and bulk operations.

Viewing Groups

Navigate to Agents > Groups tab to view all groups.

[Screenshot: Agent groups list with membership counts]

Creating Groups

1. Click Create Group
2. Enter group details:

• Name: Descriptive group name
• Description: Purpose and membership criteria
• Parent Group: Optional hierarchy

1. Configure membership:

• Static: Manually assign agents
• Dynamic: Rule-based membership

1. Click Create

[Screenshot: Create group dialog with dynamic rule builder]

Dynamic Group Rules

Define rules for automatic membership:

Match ALL of the following:
- hostname matches "SERVER-*"
- os_type equals "windows"
- domain equals "corp.local"

Match ANY of the following:
- tag contains "production"
- tag contains "critical"

Group Hierarchy

Organize groups hierarchically:

All Agents
├── Production
│   ├── Servers
│   │   ├── Web Servers
│   │   └── Database Servers
│   └── Workstations
│       ├── Engineering
│       └── Sales
└── Development
    ├── Dev Servers
    └── Dev Workstations

Child groups inherit parent policies unless overridden.

Editing Groups

1. Click the group name
2. Select Edit
3. Modify settings
4. Click Save

Deleting Groups

1. Click the group name
2. Select Delete
3. Confirm deletion

Deleting a group does not affect member agents; they become ungrouped or fall back to parent group membership.

Agent Status Monitoring

Status Definitions

Offline Threshold Configuration

Configure when agents are marked offline:

1. Navigate to Settings > Agents
2. Set Offline Threshold (default: 5 minutes)
3. Click Save

Consider network conditions when adjusting this value.

Health Monitoring

Agent health is determined by:

Alerting on Agent Status

Configure alerts for agent status changes:

1. Navigate to Settings > Notifications
2. Enable Agent Status Alerts
3. Configure thresholds:

• Alert when offline > X minutes
• Alert when degraded
• Alert on isolation changes

[Screenshot: Agent status notification configuration]

Status Dashboard Widget

Add the Agent Status widget to your dashboard for real-time monitoring:

+------------------------------------------+
|  AGENT STATUS                            |
+------------------------------------------+
|  Online     [===================] 1,245  |
|  Offline    [=]                     15   |
|  Degraded   [==]                    45   |
|  Isolated   [=]                     15   |
|  Pending    []                       5   |
+------------------------------------------+

Bulk Operations

Perform actions on multiple agents simultaneously.

Selecting Agents

• Individual: Click checkbox next to agent
• Page: Click header checkbox to select visible agents
• All: Click header checkbox, then "Select all X agents"
• Filter then Select: Apply filters, then select all

[Screenshot: Bulk selection with action toolbar visible]

Available Bulk Operations

Executing Bulk Operations

1. Select agents using checkboxes
2. Click the desired action in the toolbar
3. Review confirmation dialog:

• Number of affected agents
• Operation details
• Estimated completion time

1. Click Confirm

[Screenshot: Bulk operation confirmation dialog]

Bulk Operation Status

Monitor bulk operation progress:

1. Navigate to Agents > Operations tab
2. View active and completed operations

Uninstall and Remove Agents

Remote Uninstall

Remove the agent from endpoints remotely:

1. Select agent(s)
2. Click Uninstall in the toolbar
3. Choose uninstall options:

• Standard: Clean uninstall, remove all components
• Force: Force removal even if agent is offline
• Retain Logs: Keep local logs for forensics

1. Confirm the operation

[Screenshot: Uninstall confirmation dialog with options]

The agent will:

1. Stop all collectors
2. Remove detection rules
3. Clean up local data (unless retained)
4. Unregister from the server
5. Remove itself from the system

Removing Offline Agents

For agents that cannot be reached:

1. Select the offline agent
2. Click Remove from Console
3. Confirm removal

This removes the agent record but does not uninstall the software from the endpoint. Use this for:

• Decommissioned systems
• Reimaged machines
• Lost/stolen devices

Bulk Removal

Remove multiple agents:

1. Filter to desired agents
2. Select all matching agents
3. Click Uninstall or Remove from Console
4. Review and confirm

Retention Policy

Configure automatic removal of stale agents:

1. Navigate to Settings > Agents
2. Enable Auto-Remove Stale Agents
3. Set threshold (e.g., offline > 30 days)
4. Click Save

Agent Tags

Tags provide flexible categorization beyond groups.

Adding Tags

1. Select agent(s)
2. Click Add Tags
3. Enter tag name (or select existing)
4. Click Apply

Tag Conventions

Recommended tag formats:

Filtering by Tags

Use tags in filters:

tag:critical AND tag:prod
tag:pci OR tag:hipaa
NOT tag:legacy

Export and Reporting

Export Agent List

1. Apply desired filters
2. Click Export
3. Select format:

• CSV: Spreadsheet compatible
• JSON: Programmatic use
• PDF: Formatted report

1. Choose columns to include
2. Click Export

Scheduled Reports

Automate agent inventory reports:

1. Navigate to Reports > Scheduled
2. Click New Report
3. Select Agent Inventory template
4. Configure schedule and recipients
5. Click Save

API Access

Manage agents programmatically via API.

List Agents

curl -X GET "https://api.tamandua.io/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Agent Details

curl -X GET "https://api.tamandua.io/v1/agents/{agent_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Agent Tags

curl -X PATCH "https://api.tamandua.io/v1/agents/{agent_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["prod", "critical"]}'

See the API Reference for complete documentation.

Troubleshooting

Agent Not Appearing

1. Verify agent installation completed
2. Check network connectivity to server
3. Verify firewall allows outbound WebSocket
4. Check agent logs on endpoint
5. Verify license allows additional agents

Agent Showing Offline

1. Check endpoint is powered on
2. Verify network connectivity
3. Check agent service is running
4. Review agent logs for errors
5. Verify server-side connectivity

Agent Degraded Status

1. Click the agent to view health details
2. Identify failing component
3. Check endpoint resources (CPU, memory, disk)
4. Review component-specific logs
5. Consider restarting the agent

Next Steps

• Alert Management - Handle security alerts
• Investigations - Conduct threat investigations
• Live Response - Execute remote commands
• Dashboard Guide - Monitor agent status at scale