From 16a1982f2f4de613548da15a88c34eb2d360c37b Mon Sep 17 00:00:00 2001 From: Julien Vehent Date: Fri, 19 Sep 2014 15:01:56 -0400 Subject: [PATCH] [doc] add example of complex target query --- doc/api.rst | 2 +- doc/concepts.rst | 19 +++++++++++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/doc/api.rst b/doc/api.rst index b8824b67..8f8de279 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -145,7 +145,7 @@ The format for compliance items is simple, to be easily graphed and aggregated. .. code:: javascript { - "target": "server1.prod.example.net", + "target": "agents.name='server1.prod.example.net'", "policy": { "level": "medium", "name": "system", diff --git a/doc/concepts.rst b/doc/concepts.rst index 88999f6f..a7e86101 100644 --- a/doc/concepts.rst +++ b/doc/concepts.rst @@ -158,6 +158,25 @@ The parameters are: queries, like running an action against a specific operating system, or against an endpoint that has a given public IP, etc... + The most simple query that targets all agents is `name like '%'` (the `%` + character is a wildcard in SQL pattern matching). Targetting by OS family can + be done on the `os` parameters such as `os='linux'` or `os='darwin'`. + + Combining conditions is also trivial: `version='201409171023+c4d6f50.prod' + and heartbeattime > NOW() - interval '1 minute'` will only target agents that + run a specific version and have sent a heartbeat during the last minute. + + Complex queries are also possible. + For example: imagine an action with ID 1 launched against 10,000 endpoints, + which returned 300 endpoints with positive results. We want to launch action + 2 on those 300 endpoints only. It can be accomplished with the following + `target` condition. (note: you can reuse this condition by simply changing + the value of `actionid`) + +.. code:: sql + + id IN (select agentid from commands, json_array_elements(commands.results) as r where actionid=1 and r#>>'{foundanything}' = 'true') + .. _`agents`: data.rst.html#entity-relationship-diagram * **description** and **threat**: additional fields to describe the action