| 1 | --- |
| 2 | title: CoPilot actions |
| 3 | description: Run repeatable response actions across endpoints using CoPilot + Velociraptor, and visualize results in Grafana. |
| 4 | --- |
| 5 | |
| 6 | # CoPilot actions |
| 7 | |
| 8 | **Menu:** Agents → CoPilot Actions |
| 9 | |
| 10 | CoPilot Actions provides a more flexible way to launch endpoint actions (response + collection) across your infrastructure. |
| 11 | |
| 12 | At a high level it combines: |
| 13 | - **CoPilot** (operator UI) |
| 14 | - **Velociraptor** (executes artifacts to run the action) |
| 15 | - **Custom scripts** (the action logic) |
| 16 | - **Grafana** (dashboards to visualize action results) |
| 17 | |
| 18 |  |
| 19 | |
| 20 | Repo (required for setup assets + implementation details): |
| 21 | - https://github.com/socfortress/CoPilot-Action |
| 22 | |
| 23 | --- |
| 24 | |
| 25 | ## Why this exists (vs “traditional Wazuh Active Response”) |
| 26 | |
| 27 | Wazuh Active Response is powerful, but at scale it can become cumbersome to: |
| 28 | - deploy scripts to endpoints |
| 29 | - keep action logic consistent across OSes |
| 30 | - manage parameters and rollouts cleanly |
| 31 | |
| 32 | CoPilot Actions is designed to make automated responses **simpler to run and easier to operationalize**. |
| 33 | |
| 34 | --- |
| 35 | |
| 36 | ## How it works |
| 37 | |
| 38 | Conceptually: |
| 39 | |
| 40 | 1) You choose an action in CoPilot |
| 41 | 2) CoPilot invokes a **Velociraptor artifact** (Windows or Linux) |
| 42 | 3) The artifact downloads/executes the **action script** for the selected action |
| 43 | 4) Results are written to logs and ingested into the stack |
| 44 | 5) Grafana dashboards let you explore outcomes over time |
| 45 | |
| 46 | CoPilot’s own UI also shows: |
| 47 | - supported OS/technology |
| 48 | - action metadata + description |
| 49 | - a link to the underlying source code repo for the action |
| 50 | |
| 51 |  |
| 52 | |
| 53 | --- |
| 54 | |
| 55 | ## Prerequisites |
| 56 | |
| 57 | - CoPilot is deployed and you can access **Agents → CoPilot Actions**. |
| 58 | - Velociraptor server + clients are deployed (the CoPilot-Action repo recommends Velociraptor **0.74.1+**). |
| 59 | - CoPilot can authenticate to Velociraptor (Connector configured). |
| 60 | |
| 61 | --- |
| 62 | |
| 63 | ## Setup checklist (recommended) |
| 64 | |
| 65 | This is the practical “get it working end-to-end” checklist. |
| 66 | |
| 67 | ### 1) Import the required Velociraptor artifacts |
| 68 | |
| 69 | From the repo: |
| 70 | - `velociraptor/Linux.Execute.RemoteBashScript.yaml` |
| 71 | - `velociraptor/Windows.Execute.RemotePowerShellScript.yaml` |
| 72 | |
| 73 | Import them into Velociraptor (UI): |
| 74 | - **View Artifacts → Upload Artifacts** |
| 75 | |
| 76 | Why: these artifacts are the execution layer that downloads and runs action scripts consistently. |
| 77 | |
| 78 | ### 2) Confirm the CoPilot ↔ Velociraptor connector |
| 79 | |
| 80 | In CoPilot, configure and test the Velociraptor connector: |
| 81 | - **Connectors → Velociraptor** |
| 82 | |
| 83 | Why: CoPilot needs API access to launch the artifact executions. |
| 84 | |
| 85 | ### 3) Ensure endpoints can download action scripts |
| 86 | |
| 87 | CoPilot Actions commonly downloads scripts from public GitHub repos. |
| 88 | |
| 89 | Verify: |
| 90 | - endpoints have egress to `raw.githubusercontent.com` (or wherever your scripts live) |
| 91 | - DNS + TLS inspection/proxy rules won’t block downloads |
| 92 | |
| 93 | ### 4) (Windows) Verify PowerShell can run scripts |
| 94 | |
| 95 | If a Windows action relies on PowerShell, validate the execution policy and permissions on target endpoints. |
| 96 | |
| 97 | (Example from the repo docs: `RemoteSigned` at `LocalMachine` scope.) |
| 98 | |
| 99 | ### 5) Create SIEM routing for action output (Graylog) |
| 100 | |
| 101 | Recommended pattern: |
| 102 | - Create a dedicated **Graylog index set** (e.g., `copilot_action`) |
| 103 | - Create a **Graylog stream** that routes CoPilot Action output to that index |
| 104 | |
| 105 | Why: action output is operational/response telemetry—keep it searchable without polluting core security logs. |
| 106 | |
| 107 | ### 6) Add/verify Wazuh rule support for action output |
| 108 | |
| 109 | Action output is typically written to active response logs that the Wazuh agent already ships. |
| 110 | |
| 111 | Add/verify the supporting detection rules so the Wazuh manager can identify/classify “CoPilot Action” results. |
| 112 | |
| 113 | ### 7) Import Grafana dashboards (optional but recommended) |
| 114 | |
| 115 | The CoPilot-Action repo includes dashboards under: |
| 116 | - `Grafana/` |
| 117 | |
| 118 | Import them into Grafana and point the datasource at the CoPilot Action index. |
| 119 | |
| 120 | Why: dashboards make it much easier to confirm actions are firing and to review results across time. |
| 121 | |
| 122 | --- |
| 123 | |
| 124 | ## Repo pointers |
| 125 | |
| 126 | Everything you need to stand this up (artifacts + dashboards + docs) lives in: |
| 127 | - https://github.com/socfortress/CoPilot-Action |
| 128 | |
| 129 | --- |
| 130 | |
| 131 | ## Common tasks |
| 132 | |
| 133 | ### Find an action |
| 134 | |
| 135 | Use search to filter actions by name/technology. |
| 136 | |
| 137 | ### Invoke an action |
| 138 | |
| 139 |  |
| 140 | |
| 141 | Typical flow: |
| 142 | 1) Select an action |
| 143 | 2) Review metadata (OS support, parameters) |
| 144 | 3) Select a target agent |
| 145 | 4) Invoke |
| 146 | |
| 147 | Examples shown in the video: |
| 148 | - collecting browser history |
| 149 | - blocking an IP address via Windows Firewall |
| 150 | |
| 151 | ### View results |
| 152 | |
| 153 | Results can be viewed: |
| 154 | - in Grafana dashboards (recommended for trending/overview) |
| 155 | - in Velociraptor execution logs/results (best for deep troubleshooting) |
| 156 | |
| 157 |  |
| 158 | |
| 159 | --- |
| 160 | |
| 161 | ## Troubleshooting (fast checks) |
| 162 | |
| 163 | If an action fails: |
| 164 | - Confirm the required Velociraptor artifacts exist and are runnable |
| 165 | - Check the Velociraptor artifact execution **logs/results** for errors |
| 166 | - Verify Graylog stream/index routing if you expect results in dashboards |
| 167 | - Confirm endpoint prerequisites (PowerShell availability, script paths, permissions) |
| 168 | |
| 169 | --- |
| 170 | |
| 171 | ## Gotchas |
| 172 | |
| 173 | - Actions can be disruptive (containment/firewall changes). Use approvals + logging. |
| 174 | - Start by testing actions on a lab endpoint and then roll out. |
| 175 | - Ensure your routing keeps action output separated from core security telemetry. |
| 176 | |
| 177 | --- |
| 178 | |
| 179 | ## Video context |
| 180 | |
| 181 | Feature walkthrough + setup approach: |
| 182 | - https://www.youtube.com/watch?v=l9OLtgemYOQ |