Investigations

An investigation is a saved workspace for one line of inquiry. It holds an ordered list of artifacts. Each artifact is a named VFQL query, with the latest run of that query and its results.

Use an investigation when a question needs several queries: find the failing logins, then pivot to what those accounts did next. It keeps the queries in order, next to their results, where your team can open them.

Create an investigation

There are two ways.

From a query you just ran. On the Run Query page, run a query. When it succeeds, click Save as Investigation. Vigilfield creates an investigation named "Untitled investigation" with one artifact, "Query 1", and opens it.

From scratch.

1. In the sidebar, open Investigations.
2. Click New Investigation.
3. Enter an Investigation Name. It is required. A Description is optional.
4. Click Create Investigation. The new investigation opens.

To create an investigation inside a folder, open the folder and click New Investigation there. See Folders.

A new investigation belongs to the team you are acting as when you create it.

Work with artifacts

The Artifacts section lists the investigation's queries, top to bottom.

Add an artifact

Click Add Artifact (or Add First Artifact in an empty investigation). A new artifact appears at the bottom, named "Query" and its position, such as "Query 2".

Write and run the query

1. Type VFQL in the artifact's editor. For example:

   SecurityEvents | where Account in (Assets | project Account)

2. Click the artifact's Run button, or press Ctrl+Enter (⌘+Enter on a Mac).

The editor checks the query as you type, as on the Run Query page. While the query runs, a spinner shows next to the artifact's name. A green check means it succeeded. A red mark means it failed or was cancelled, and the error shows under the editor.

When the run succeeds, the header shows the engine time and the row count, and the results appear under the editor, 100 rows per page. View query opens the run's own page. See Queries.

Download results

When an artifact has results, click Download CSV. The file holds the page of results on screen, up to 100 rows, not the full result. For the full result, open View query and follow the Result table link.

Rename, reorder, collapse, delete

• Rename: click the artifact's name, type the new name, and press Enter. Press Escape to cancel.
• Reorder: drag the handle on the left of the artifact's header. The new order is saved for everyone.
• Collapse: click the arrow on the right of the header to hide or show the editor and results.
• Delete: click the trash icon on the header.

Edit or delete the investigation

On the investigation's page:

• Edit changes the name and description.
• Delete removes the investigation and its artifacts. The app asks you to confirm. This cannot be undone.

The query runs the artifacts pointed at are not deleted. They stay in your query history until their results expire.

Duplicate an investigation

On the Investigations page, in the card view, open an investigation card's menu and click Duplicate.

The copy is named after the original with " (Copy)" added. It is in the same folder and belongs to the same team. Its artifacts are copied in the same order. They point at the same query runs as the originals, so the copy shows the same results without running anything again.

To duplicate, you need read access to the original, and write access for the team the copy belongs to.

Who can see an investigation

An investigation belongs to a team. The Investigations page lists only the investigations you can read. The Who can access this panel at the bottom of an investigation shows which teams can act on it, and with which actions, after grants and any resource policy are combined.

Access to the investigation does not grant access to data. To see an artifact's results, you need query access to every table its run read. A teammate without that access can open the investigation but cannot read those rows.

Admins can use Run as admin (audited) below the artifacts to run artifacts against system tables. The override applies only to that click. It is never saved on the artifact, so anyone who runs the artifact again runs it under their own access. See System tables and the admin override.

Over the API

• Investigations: GET /investigations, POST /investigations, GET, PUT and DELETE /investigations/{id}, and POST /investigations/{id}/copies to duplicate.
• Artifacts: GET and POST /investigations/{investigationId}/artifacts, and GET, PUT and DELETE /investigations/{investigationId}/artifacts/{id}.

An artifact stores a name and last_query_id, the id of its latest query run. It does not store query text. To run an artifact over the API, submit the query with POST /queries, then set the artifact's last_query_id to the new run's id.

An investigation's artifact_ids is the artifact order. To reorder, send the same ids in a new order with PUT /investigations/{id}. The list must contain exactly the investigation's current artifacts, with no duplicates. To add or remove an artifact, use the artifact endpoints instead.

An artifact name must not be blank.