Skip to main content

Extracted Files

New in EveBox 0.30.0

Extracted file previews and downloads are only available in EveBox 0.30.0 and newer, not in EveBox 0.29 or earlier releases. The feature is still under active development and its configuration keys and behaviour may change.

The EveBox Server can offer previews and downloads of files that Suricata extracted with its file-store output. The files can come from a file store on the EveBox Server host, or from an EveBox Agent running on a remote sensor.

When a file source is available and the event references a file with a valid SHA-256 digest, the event view shows file actions in the header of the file information card of fileinfo events, and of the files card of alerts. For a single file, select Preview to inspect it, or choose Download from the adjacent menu. For multiple files, the Files menu offers both actions for each file.

Untrusted Content

Extracted files are captured from the network and may be malicious. Full downloads are named by their SHA-256 digest, never under the file name seen on the network. Previews display only derived information, hex, decoded text, and strings; EveBox does not render extracted files as HTML, images, media, or framed documents. Previewing does not send file content to third-party services. Handle downloaded files with care.

Previewing a File​

The preview reads at most the first 64 KiB (65,536 bytes) of a file, from either the server-local store or a remote agent. Larger files are not loaded in full; the preview indicates how much was loaded and provides a button to download the complete file.

The preview has four tabs:

  • Info: file metadata, detected type, entropy, serving source, and warnings about mismatches or incomplete content.
  • Hex: a hexadecimal view of the loaded bytes.
  • Text: decoded text with encoding selection, wrapping, line numbers, and an option to show hidden control characters.
  • Strings: extracted ASCII and UTF-16LE strings, with minimum-length selection and filtering.

Probable text files open on the Text tab; other files open on Info. Inspection applies only to the loaded bytes, so a prefix preview may not show information found later in the file. The preview cap is fixed and does not limit full downloads.

Prerequisites​

  • Suricata's file-store output must be enabled with version: 2. Version 2 stores files by their SHA-256 digest, which is how EveBox finds them. The older version 1 layout is not supported.
  • The events must include each file's sha256. Suricata includes it in fileinfo events and in an alert's files when file-store version 2 is enabled.
  • The file-store directory must be readable by the EveBox Server or Agent process that serves it.
  • For a server-local source, the server must run on the host that has access to the file store. Otherwise, run an EveBox Agent on the sensor host.

Suricata Configuration​

A minimal file-store entry under Suricata's outputs section:

- file-store:
    version: 2
    enabled: yes
    dir: /var/log/suricata/filestore

Suricata only stores files matched by rules using the filestore keyword unless force-filestore: yes is set. See the Suricata documentation for the full set of file-store options. Suricata does not prune the file store itself, so plan for its retention separately.

Server-Local File Store​

When Suricata and the EveBox Server run on the same host, point the server at the file-store directory on the command line:

evebox server --filestore-directory /var/log/suricata/filestore

with the EVEBOX_FILESTORE_DIRECTORY environment variable, or in the configuration file:

filestore:
  directory: /var/log/suricata/filestore

Setting the directory is what enables the feature; there is no separate enable flag. The local store is shown as (server) when a source must be selected. Like server-local packet capture, it serves events ingested by the server's own input.

If the directory does not exist yet, EveBox logs a warning and continues.

Remote Agents​

An EveBox Agent on the sensor can serve its local file store over the same authenticated control connection used for packet capture. The agent needs a server connection and an agent key created on the server with evebox config agents add <name>.

Add the file-store directory to the agent's agent.yaml:

server:
  url: https://evebox.example
  key: eba_...

# File serving requires the EveBox Server connection and is not
# available when the agent writes directly to Elasticsearch.
elasticsearch:
  enabled: false

filestore:
  directory: /var/log/suricata/filestore

or use --filestore-directory on the evebox agent command line. Unlike the server, the agent has no EVEBOX_FILESTORE_DIRECTORY environment-variable setting.

An agent can serve packet captures and files at the same time, or only one of them. Like a PCAP-only agent, an agent with no EVE inputs keeps its control connection open and serves requests without shipping events. Unlike packet capture, file serving is also supported by agents running on Windows.

Once connected, the agent lists filestore among its capabilities on the Administration → Agents page.

Routing​

File previews and downloads are routed to a source the same way as packet capture downloads. The routing table on the Administration → Agents page, named Source Routing from EveBox 0.30.0, is shared by both features. A rule's source must be able to serve the requested data: a rule pointing to an agent that serves only packet capture fails for file previews and downloads instead of falling back to another source.

Limits​

  • Each agent serves one file download and one file preview at a time. These are separate from each other and from packet capture requests. Further requests of the same kind to that agent receive a busy response.
  • At most 16 remote file jobs, counting both downloads and previews, run at once across all agents. These concurrency limits do not apply to server-local file requests.
  • A remote transfer fails if the agent stops sending data for 60 seconds, or if its control connection drops during the transfer.

A file can be missing even when the event references it: Suricata may not have stored it, or it may have been pruned from the file store since. EveBox reports a missing file as an error in the web interface rather than starting an empty download.