Argus Event REST MCP Tools

These tools let the LLM retrieve Argus event data, calculate event statistics, fetch event details, and inspect event lineage from the Argus event API.

They support five common tasks:

• list events associated with a case
• search events using structured criteria
• calculate event statistics using structured filters and aggregation instructions
• fetch one event by its event identifier
• fetch event lineage by event identifier

General Notes

• Use these tools when you want the LLM to retrieve live event data or event statistics from Argus APIs.
• For event searches, the LLM should first use the Event Search Translator MCP tools to shape and validate the search request.
• For event statistics, the LLM should first use the Event Search Translator MCP tools to shape and validate the statistics request.
• Search results and case-associated event listings are paginated. limit controls how many results are returned, and offset controls where the page starts.
• Event search and case-associated event listing use page sizes from 1 to 100.
• Each search or list call returns only one page. It does not automatically fetch additional pages.
• Search responses include pagination metadata under page, such as nextOffset, stop, and reason, which the LLM can use if you ask it to continue.
• Event identifiers must use the canonical three-part format timestampEpochMillis/customerID/eventUUID.
• Statistics responses are source-of-truth aggregation trees. The LLM should explain counts and metrics from returned buckets only, without inventing missing buckets or values.

Event Identifier Format

The event detail and lineage tools require an event identifier in this format:

timestampEpochMillis/customerID/eventUUID

Example:

1762428410440/1/b18fb75e-0587-4570-a467-092a503f9294

If the user provides an identifier with a leading event-type prefix, such as RAW/, AGGR/, or NIDS/, the LLM should remove that prefix before using the identifier.

Example conversion:

RAW/1762428410440/1/b18fb75e-0587-4570-a467-092a503f9294

becomes:

1762428410440/1/b18fb75e-0587-4570-a467-092a503f9294

If the identifier cannot be converted into the canonical three-part format, the LLM should ask for a valid event identifier instead of guessing missing parts.

Tool: getEventsAssociatedWithCase

Purpose

List Argus events associated with a specific case.

Arguments

Field	Description	Type	Default	Required
caseID	Case ID whose associated events should be returned.	number	None	Yes
limit	Maximum number of events to return in this call. Accepted range: 1 to 100. Use 25 when no specific page size is requested.	number	None	Yes
offset	Number of matching events to skip before returning results. Use 0 for the first page.	number	None	Yes

Usage Notes

• limit = 0, negative limits, and limits above 100 fail validation.
• Use offset = 0 for the first page unless the user asks for a later page.
• For more than 100 results, the LLM can make repeated calls with increasing offset if you ask it to continue.
• A common paging pattern is: next offset = previous offset + limit.

Tool: executeSearchArgusEvent

Purpose

Retrieve Argus event search results for event search criteria prepared from the user's intent.

Arguments

Field	Description	Type	Default	Required
request	Full event search definition prepared and validated from the user's request.	object	None	Yes
includeProperties	Whether event properties should be included in returned results. Use true only when event properties or details are explicitly requested in result rows.	boolean	false	No

request Fields

Field	Description	Type	Default	Required
associateCaseID	Match events associated with any of these case IDs. 0 means events with no associated case.	array<number>	None	No
attack	Attack-related criteria. Each item is one criterion.	array<object>	None	No
customer	Match events belonging to any customer ID or short name.	array<string>	None	No
domainName	Match events with any of these domain names.	array<string>	None	No
endpoint	Endpoint-related criteria for source or destination endpoints.	array<object>	None	No
severity	Match event severity. Allowed values: low, medium, high, critical.	array<string>	None	No
eventIdentifier	Match specific event identifiers in canonical timestamp/customerID/eventID format.	array<string>	None	No
type	Match event types. Allowed values: aggregated, raw.	array<string>	None	No
timeFilter	Time-based narrowing for event search.	object	{ "timeField": ["created"], "startTime": "startOfDay", "endTime": "now", "timeMatchStrategy": "any" }	No
includeEventFlag	Event flags that matching events must contain. Values should be resolved with the event search translator list tools.	array<string>	None	No
excludeEventFlag	Event flags that matching events must not contain. Values should be resolved with the event search translator list tools.	array<string>	None	No
property	Event property criteria.	array<object>	None	No
page	Pagination settings.	object	{ "limit": 25, "offset": 0 }	No
sortBy	Search result sort order. Use list order as priority. Prefix with - for descending. Values should be resolved with the event search translator list tools.	array<string>	None	No

request.attack[] Fields

Field	Description	Type	Default	Required
alarm	Match events triggered by any of these alarms, using alarm ID or short name.	array<string>	None	No
attackCategory	Match events in any of these attack categories, using ID or short name.	array<string>	None	No
signature	Match events triggered by any of these security signatures.	array<string>	None	No
exclude	Negate this attack criterion.	boolean	false	No
required	Require this attack criterion to match together with other criteria.	boolean	true	No

request.endpoint[] Fields

Field	Description	Type	Default	Required
countryCode	Match endpoint country codes.	array<string>	None	No
endpointFieldStrategy	Which endpoint side to search. Allowed values: source, destination, all.	string	all	No
ip	Match endpoint IPs or CIDR networks. Supports IPv4, IPv6, and CIDR notation.	array<string>	None	No
minMaskBits	Minimum CIDR prefix length to match. Useful to exclude broad subnets.	number	None	No
port	Match endpoint ports.	array<number>	None	No
includeEndpointFlag	Endpoint flags that must be present. Values should be resolved with the event search translator list tools.	array<string>	None	No
excludeEndpointFlag	Endpoint flags that must not be present. Values should be resolved with the event search translator list tools.	array<string>	None	No
exclude	Negate this endpoint criterion.	boolean	false	No
required	Require this endpoint criterion to match together with other criteria.	boolean	false	No

request.timeFilter Fields

Field	Description	Type	Default	Required
timeField	Event time fields the range applies to. Allowed values: created, lastUpdated, firstAssessment, enginePersisted, firstEvent, lastEvent, published, all.	array<string>	["created"]	No
startTime	Start of the time range. Accepts epoch millis as string, ISO-8601 UTC, or relative expressions such as startOfDay - 1 day.	string	startOfDay	No
endTime	End of the time range. Accepts epoch millis as string, ISO-8601 UTC, or relative expressions such as now.	string	now	No
timeMatchStrategy	How to evaluate multiple timeField values. Allowed values: any, all.	string	any	No

request.property[] Fields

Field	Description	Type	Default	Required
key	Property key to match.	string	None	Yes
value	Property values to match against the key.	array<string>	None	Yes
valueMatchStrategy	How to combine multiple values. Allowed values: any, all.	string	any	No
valueSearchStrategy	How to compare each value. Allowed values: tokenized, exact.	string	exact	No
exclude	Negate this property criterion.	boolean	false	No
required	Require this property criterion to match together with other criteria.	boolean	false	No

request.page Fields

Field	Description	Type	Default	Required
limit	Maximum number of events per page. Accepted range: 1 to 100.	number	25	No
offset	Number of events to skip before returning results. Must be 0 or greater.	number	0	No

Usage Notes

• The LLM should use generateArgusEventSearchQuery before executing an event search so event flags, endpoint flags, sort fields, pagination, and identifiers are validated.
• If more than one page is needed, ask the LLM to continue fetching additional pages. The tool itself returns one page at a time.
• Descending sorting uses a - prefix, for example -createdTimestamp.
• If event properties are needed in result rows, ask for properties explicitly so includeProperties can be set to true.

Tool: executeCalculateStatisticsArgusEvent

Purpose

Calculate statistics for Argus events matching the selected filters. The result can include grouped buckets and time-based timeline metrics.

Arguments

Field	Description	Type	Default	Required
request	Event statistics definition prepared and validated from the user's request.	object	None	Yes

request Fields

Field	Description	Type	Default	Required
filter	Filters that select which events are included before statistics are calculated.	object	Default event filter with created-time range from startOfDay to now	No
statistics	Statistics outputs to calculate. Must include groupBy, timeRangeMetrics, or both.	object	Empty object	Yes

request.filter Fields

These filters use the same shape as event search filters, except there is no pagination, sorting, or includeProperties option.

Field	Description	Type	Default	Required
associateCaseID	Include events associated with any of these case IDs. 0 means events with no associated case.	array<number>	None	No
attack	Attack-related criteria.	array<object>	None	No
customer	Include events for any customer ID or short name.	array<string>	None	No
domainName	Include events with any of these domain names.	array<string>	None	No
endpoint	Endpoint-related criteria.	array<object>	None	No
severity	Include event severities. Allowed values: low, medium, high, critical.	array<string>	None	No
eventIdentifier	Include specific event identifiers in canonical timestamp/customerID/eventID format.	array<string>	None	No
type	Include event types. Allowed values: aggregated, raw.	array<string>	None	No
timeFilter	Time range selecting the event population for statistics.	object	{ "timeField": ["created"], "startTime": "startOfDay", "endTime": "now", "timeMatchStrategy": "any" }	No
includeEventFlag	Event flags that events must contain. Values should be resolved with the event search translator list tools.	array<string>	None	No
excludeEventFlag	Event flags that events must not contain. Values should be resolved with the event search translator list tools.	array<string>	None	No
property	Event property criteria.	array<object>	None	No

request.statistics Fields

Field	Description	Type	Default	Required
groupBy	Fields by which to group statistics. Order controls the aggregation hierarchy.	array<object>	None	Required if timeRangeMetrics is omitted
timeRangeMetrics	Time-based timeline metrics to calculate over the filtered events.	array<object>	None	Required if groupBy is omitted

At least one of groupBy or timeRangeMetrics is required for a valid statistics request.

request.statistics.groupBy[] Fields

Field	Description	Type	Default	Required
field	Event field to group by. Allowed values: signature, attackCategory, alarm, location, severity, sourceIP, destinationIP, protocol, customer, sourceCountry, destinationCountry, associatedCase.	string	None	Yes
limit	Maximum number of distinct buckets for this group field. Minimum 1.	number	25	No

request.statistics.timeRangeMetrics[] Fields

Field	Description	Type	Default	Required
name	Unique metric name for the timeline metric. Use letters, numbers, underscore, colon, dash, or dot.	string	None	Yes
timestampField	Event timestamp field to bucket. Allowed values: created, lastUpdated, firstAssessment, enginePersisted, firstEvent, lastEvent.	string	None	Yes
resolution	Timeline bucket size. Allowed values: minutes, hours, days, weeks, months, years.	string	None	No
includeEmptyBuckets	Whether empty time buckets should be included.	boolean	None	No

Statistics Response Notes

• The response is a scoped tree, not a flat list.
• If no groupBy fields are requested, the top-level bucket represents all matching events.
• If groupBy is requested, child buckets are scoped by their parent buckets and follow the requested group order.
• Metrics apply only to the bucket where they appear.
• Empty buckets, rangeMetrics, or statisticsMetrics arrays mean there are no child buckets or metrics at that level.
• The LLM should not combine buckets just because display names match; identity fields such as identifiers should be preferred when available.

Usage Notes

• The LLM should use generateArgusEventStatisticsQuery before calculating event statistics so event flags, endpoint flags, required statistics instructions, and identifiers are validated.
• The statistics filter time range selects the events included in the calculation.
• Timeline metric start and end timestamps follow the filter time range.
• Event statistics do not support numeric summary metrics; use groupBy and timeRangeMetrics.
• Event statistics timeline fields are narrower than search time fields. For example, published can be used in search time filters but is not a valid timeline metric timestamp field.

Tool: getArgusEventByIdentifier

Purpose

Fetch full event details for one specific event identifier. Details include comments, properties, and sub-event identifiers when available.

Arguments

Field	Description	Type	Default	Required
eventIdentifierString	Event identifier to look up. Use canonical timestamp/customerID/eventID format without a leading event-type prefix.	string	None	Yes

Usage Notes

• Prefixes such as RAW/, AGGR/, and NIDS/ should be removed before lookup.
• Invalid identifiers fail parsing. The LLM should ask for a valid identifier instead of guessing missing timestamp, customer ID, or UUID values.

Tool: getArgusEventLineageByIdentifier

Purpose

Fetch event lineage records for one specific event identifier.

Arguments

Field	Description	Type	Default	Required
eventIdentifierString	Event identifier whose lineage should be returned. Use canonical timestamp/customerID/eventID format without a leading event-type prefix.	string	None	Yes
limit	Maximum number of lineage records to return in this call. Use 25 when no specific page size is requested.	number	None	Yes
offset	Number of lineage records to skip before returning results. Use 0 for the first page.	number	None	Yes

Usage Notes

• Prefixes such as RAW/, AGGR/, and NIDS/ should be removed before lookup.
• Invalid identifiers fail parsing. The LLM should ask for a valid identifier instead of guessing missing timestamp, customer ID, or UUID values.
• The tool fetches one page at a time. For more lineage records, the LLM should make another request with offset = previous offset + limit.
• The tool description recommends limit values from 1 to 100, but this method does not perform the same local limit validation as event search and case-associated event listing. Use 1 to 100 to stay aligned with the API guidance.