Files and console
An endpoint's page has two live tabs, under its Live response tab. Files lets you browse the host's file system. Console lets you run read-only commands and osquery SELECTs on it. Both talk to the endpoint in real time, both are read-only, and everything you do in them is recorded under your name.
This feature is currently rolling out and may not be enabled for your organization. Files and Console are a separate rollout from the Endpoints workspace: the two tabs may be missing from an endpoint's page even when Endpoints is on.
If you are deciding whether to enable this for your team, start with What is recorded.
Who can use them
You need to be an admin of the fleet's connection or hold the Responder role on the fleet or on a tag the endpoint carries. See Access and activity.
| What you see | Why |
|---|---|
| The tab is disabled, with "You don't have permission to browse files on this fleet. Ask a fleet admin for access." (or the same for console commands) | You don't hold the role. |
| File browsing isn't available on this fleet or Console isn't available on this fleet | The feature is turned off for this deployment. Nothing was opened. |
| This fleet is shared — view only | Sessions can't be opened on a fleet that serves more than one organization. |
Sessions
Nothing happens when you open the tab. A session starts only when you click Start browsing or Start console session, because opening a session, and every listing, file and command after that, is written to the audit trail under your name. The notice Everything you do here is recorded says so before you start.
While a session is open, one status row above it shows:
- Session active.
- A countdown — Idle timeout in and the time left. The session closes after 5 minutes without activity; it is kept alive while the tab is visible. Near the end of a long session the countdown switches to Ends in, because sessions last at most one hour.
- How many requests or commands you have made this session.
- Where it is rolled out, live response: its state, Start live response, Cancel or End live response, and how many shared slots are in use. Hover for details.
- End session, to close it yourself.
| A session ends when… | What you see |
|---|---|
| You click End session | "You ended this session." |
| You leave the tab, reload, or navigate away | The session is closed for you. |
| It sits idle | "The session was idle for 5 minutes and expired." |
| It reaches the maximum length | "The session reached its one-hour maximum." |
| You open a newer session on the same endpoint, for example in another tab | The older one is replaced. |
| A fleet admin ends it | "A fleet admin ended this session." |
After that you see This session has ended and Start a new session. Starting again is recorded, like the first time. Console output that was on screen stays visible until you leave the tab.
Session limits
There is a limit on how many sessions you, and your team, can have open at once. When you reach it you see Session limit reached — "Close one to open another" — and, when Huntbase knows, how long to wait: idle sessions expire on their own.
Browse files
- Open the endpoint's page and click the Files tab.
- Click Start browsing.
- Type a path and click Go, or click folders in the listing. Use Back, Forward, Up one level and the breadcrumb to move around. Refresh lists the directory again, and is recorded as a new request.
- Click a file to open its details: Path, Size, Mode, Owner (uid:gid), and the Modified, Accessed and Changed times.
The listing has the columns Name, Size, Modified, Owner (uid:gid), Mode and Type; click a header to sort.
Browsing is read-only. Nothing is downloaded until you collect a file: click Collect on a file's row, or Collect file in its details, to open the Collect file dialog with the path filled in.
| Message | Meaning |
|---|---|
| Queued — waiting for the endpoint to check in (up to about a minute) | The request waits for the endpoint's next check-in. With live response it says Running… and returns in about a second. |
| The endpoint did not pick this up — it may be offline | Requests wait about a minute for the endpoint to check in, then expire. Try again once it is back online. |
| The endpoint could not read this path | It may not exist, or the endpoint software may not be allowed to read it. |
| "This directory is empty, or the endpoint software can't read it." | Shown for an empty listing. |
| The result was too large | List a smaller directory. |
Use the console
- Open the endpoint's page and click the Console tab.
- Click Start console session.
- Type a command at the prompt and press Enter. Use the up and down arrows to recall earlier commands, and Ctrl+L to clear the screen.
The console looks and behaves like a terminal: each command is followed by its output, and the prompt is the last line. Its first lines remind you that it is read-only and that every command's text is recorded under your name, while the output never is. While a command runs, the prompt is replaced by its progress, and it comes back when the command finishes.
The console is read-only, but powerful: it cannot change the endpoint, but a SELECT can read almost anything osquery exposes on it — processes, users, file metadata, network state. A session runs one command at a time. Without live response, a command waits for the endpoint's next check-in: you see Queued — waiting for the endpoint to check in (up to about a minute) and then Delivered — waiting for the endpoint's answer…. While the endpoint is live you see Running… instead, and the answer comes back in about a second. When live response is available but not started, the queued line suggests starting it. If the endpoint is offline it never picks the command up, and the command expires after about a minute.
Results appear as a plain-text table, like osqueryi's, followed by the row count and how long the command took. Hover over a result to copy it; a table is copied as tab-separated text, with every row and every character. Errors appear as plain text lines. If a result says it was truncated, add a WHERE clause or a LIMIT.
Commands
Open What can I run here? under the console for this reference in the app.
| Command | What it does |
|---|---|
pwd | Print the current directory. |
cd <path> | Change the current directory. |
ls [path] | List a directory. |
stat <path> | Show one file's metadata. |
ps | List running processes. |
sql <select…> | Run one osquery SELECT without switching mode. |
osquery / sql | Switch to osquery mode: every line is a SELECT. |
help | Show the console's own help. |
clear | Clear this scrollback (nothing is sent). |
osquery mode
In osquery mode every line you enter is a query. Type exit to leave the mode.
- Each line is one statement and must start with
select. - No
;, and no insert, update, delete, drop, alter, attach, detach or pragma. - Up to 4,000 characters, on one line.
What is refused, and why
| Refused | Why |
|---|---|
get, the carves table and carve() | Pulling a file through the console would skip the file-collection permission, its audit record and your storage destination. Use Collect file instead, so the collection is permissioned, recorded and stored in your bucket. |
The curl and curl_certificate tables | They make the endpoint send network requests. |
A refused command shows That command isn't allowed here.
Save a console session to a hunt
Save to hunt, in the console session's status row, adds the session to a hunt's notebook as a read-only Endpoint transcript cell: each command, when it ran and how it turned out, with the live response and response actions from the same time.
- Click Save to hunt.
- Pick one of your open hunts. You need to be able to contribute to it.
- Leave Include command output off to save commands and outcomes only, or turn it on to save the output too.
- Click Save to hunt. Open in the confirmation takes you to the new cell.
Command output is not saved unless you turn it on. When you do, the output becomes part of the hunt: everyone who can see the hunt can read it, and it is kept for as long as the hunt is. Very long transcripts are cut to fit, and the cell says so.
In a hunt, Scout can propose saving a console session for you; the proposal waits for someone to approve it. To run read-only checks from the hunt itself, use an endpoint check cell.
Saving is available where response actions are rolled out.
Live response
Endpoints normally check in about once a minute, so a listing or a command waits up to a minute before it runs. Live response opens a short-lived, direct connection to one endpoint. While it is live, your Files and Console requests are sent to the endpoint straight away and results come back in about a second.
Live response is a separate rollout from Files and Console. You see its controls only when it is enabled for your organization and the fleet supports it.
Live response changes how fast requests travel, not what they can do. Every request is still read-only, still refused by the same rules, and still recorded in the same way. See What is recorded.
Start live response
Choose Respond › Start live response in the endpoint page's header, or click Start live response in the Files or Console tab before you start a session, or in the session's status row once one is open. You need the same permission as for the console. On a shared fleet, or without the permission, it is disabled and says why. It is also disabled when the endpoint hasn't checked in for 15 minutes. The bar then reads Endpoint offline — last seen 3 hours ago, because a session would only connect at the next check-in and would hold a shared slot until then.
A request goes through these states:
| State | What you see | What it means |
|---|---|---|
| Queued | Queued for live response — 2nd in line, how long you have waited, and Cancel. | All live response slots are in use. Yours starts as soon as one frees up. Until then, commands still run at normal check-in speed. |
| Connecting | Waiting for the endpoint's next check-in, with an elapsed timer, and Cancel. | A slot is reserved. The endpoint picks up the request at its next check-in, about once a minute, then connects. Commands you run now are sent at that check-in. |
| Live | Live — results come back in about a second (in a session's status row, Live · ~1s responses), a countdown to the idle limit, a countdown to the one-hour limit, and End live response. In the status row, hover for the countdowns. | Requests are sent to the endpoint straight away. |
| Ended | Live response ended, the reason, and Start again. | The slot is back in the pool. Requests go back to normal check-in speed. |
The first connection always waits for one check-in, so expect up to about a minute before the endpoint goes live. After that, results come back in about a second.
Limits
| Limit | What happens |
|---|---|
| 5 minutes without activity | Live response ends when nothing has been sent to the endpoint for 5 minutes. |
| 1 hour | Live response ends after one hour, however busy it is. Start it again if you still need it. |
| One per endpoint | An endpoint has at most one live response at a time. |
The shared pool and the queue
Live response slots are shared by every fleet on the deployment, and each environment has a smaller limit of its own. Next to the control, Live response: 12 / 15 in use shows how many slots are taken; hover it to see your fleet's environment's share. When every slot is in use, a new request joins a queue and starts in order, first come first served, as slots free up. A request that waits too long in the queue expires.
End live response when you are done, so the slot goes back to the pool for other responders.
When someone else started it
If another responder already has live response on the endpoint, you see its state, marked Started by another responder, but you can't cancel or end it — unless you approved the endpoint action that started it, in which case Cancel or End live response is there for you too. Your own Files and Console requests are fast while it is live too. A connection admin can end it for everyone.
Live response started from an approved proposal belongs to the person who asked for it, not the approver, so the requester can use it straight away.
Why live response ended
| Reason | What you see |
|---|---|
| You ended it | "You ended live response." |
| You cancelled it while queued | "The request was cancelled before it started." |
| It waited in the queue too long | "The request waited in the queue too long and expired." |
| It sat idle | "Nothing was sent to the endpoint for 5 minutes, so live response ended." |
| It reached the maximum length | "Live response reached its one-hour limit." |
| Safe mode was turned on for the fleet | "Safe mode was turned on for this fleet, which ends live response." |
| A fleet admin ended it | "A fleet admin ended live response." |
| The endpoint didn't connect in time | "The endpoint didn't connect in time — it may be offline or asleep." |
| The connection dropped | "The connection to the endpoint was lost." |
| The endpoint was removed | "The endpoint was removed from its fleet." |
| The endpoint's software is too old, or refused | The endpoint's software doesn't support live response, or it refused the connection. |
What is recorded
Security teams should know exactly what these tabs leave behind.
| Recorded in the audit trail | Never recorded or stored by Huntbase | |
|---|---|---|
| Console | Opening and closing a session; every command, with its full text; who ran it and on which endpoint; refused attempts. | Command output. It exists only in your browser tab until you leave it. |
| Files | Opening a session; every directory you list and file you inspect, with the path; refused attempts. | The listing itself and file contents. |
- Recorded before it runs. Each action is written to your organization's audit trail, under your name, before it runs. If that write fails, nothing runs and you see Blocked: the action could not be recorded.
- Sessions are personal. A session can only be used by the person who opened it.
- Hunt endpoint cells keep their rows. Checks, snapshots and watches run from a hunt's endpoint cells store their rows on the cell, where only people on the hunt who can see the endpoint can read them. Their commands are audited like yours, and so is everything Scout does on your behalf.
- Saving to a hunt is recorded. The audit trail notes which hunt, how many commands, and whether output was included. Output is only stored when you choose to include it, and then only in the hunt.
- Live response is recorded too. Queuing, starting, ending and cancelling live response are written to the audit trail under your name, with the reason and how long it lasted. It records no commands or output of its own: those stay under the Console and Files rules above.
- Read-only by design. Neither tab can change the endpoint, and the console refuses commands that would move files or make the endpoint send network requests.
- Files leave the endpoint one way only — through Collect file, into a bucket your organization owns.
- Fleet admins review all of it on the fleet's Activity tab, including denied attempts.
Next steps
- Access and activity — grant the Responder role and read the audit trail
- Collect files — retrieve a file you found
- Endpoints and endpoint details — the rest of the endpoint's page
- Query languages — osquery syntax