Digital Forensics Investigation

This document describes how to use Sec-Gemini for performing a digital forensics investigation based on logs.

Quickstart with Chronicle (Google SecOps)

This assumes your logs are managed by Chronicle. In this setting, Sec-Gemini will query the logs in your Chronicle instance, via your local network connection.

Launch Sec-Gemini TUI in DFIR mode

Run the following command to launch Sec-Gemini TUI with the Chronicle backend:

sec-gemini dfir --chronicle=CUSTOMER_ID,PROJECT_ID,REGION

For example:

sec-gemini dfir --chronicle=12345678-9abc-def0-1234-567890abcdef,chronicle-project,us

Perform the Investigation

Once the TUI is ready and a new session established, prompt Sec-Gemini to perform a forensics investigation.

If you want Sec-Gemini to perform an unhinted investigation (i.e., operate in threat hunting mode), your prompt can be as simple as:

Perform a forensics investigation on the available logs.

When a starting point is available, or if you want to focus the agent's attention on a specific part, you may provide the information in the prompt itself. Here are good examples of additional information to provide:

an (approximate) incident time, e.g., 2026-05-06 13:00
a hostname
an account or username
a specific filename

For instance:

Perform a forensics investigation on the available logs.
An alert was triggered at 2026-05-06 13:00 on hostname "machine1234".

Advanced Usage

Custom Logs in an SQLite DB file

If your logs are not managed by Chronicle, you can store them in a local SQLite3 database file, which Sec-Gemini repeatedly queries during the investigation. To run the Sec-Gemini TUI for digital forensics using logs stored in an SQLite DB file, use the following command:

sec-gemini dfir --sqlite=PATH_TO_FILE.DB

Alternatively, if you have multiple SQLite DB files, each corresponding to exactly one investigation to perform, you can name them following the convention TICKET_ID.db, where ticket IDs are always numerical, e.g., 12345.db, and place them in the same directory. You can use the same command as before by providing the path to the directory instead of the path to the file:

sec-gemini dfir --sqlite=PATH_TO_DIRECTORY_OF_DB_FILES

If you have more than one logs DB file, you must tell Sec-Gemini which one to perform the digital forensics investigation on in the prompt, for example:

Perform a forensics investigation on the logs with ticket ID 12345.

Expected SQLite DB Schema

The SQLite3 database file must contain two tables with the following schemas:

records Table

Notice that log records do not need to be parsed or otherwise structured beyond providing a timestamp. You may use arbitrary values for the log_type field, or even a single value for all records, as long as each value has a corresponding entry in the log_descriptions table below.

log_descriptions Table

SDK Usage (Non-TUI)

You can also use the Python SDK to perform a digital forensics investigation. In this case, you need to manually run the local BYOT server which acts as the logs MCP server. Note that when using the TUI, this step is automated.

1. Run the local logs MCP server

The forensics capability of Sec-Gemini is designed to operate on logs that are both massive in quantity (multiple TBs) and sensitive. To give Sec-Gemini the ability to access the logs under investigation, you run a local logs MCP server. The logs MCP server is built into the sec-gemini-byot binary.

There are currently two supported log sources for the local logs MCP server:

Chronicle (Google SecOps)

sec-gemini-byot --no-base-tools --dfir-chronicle=CUSTOMER_ID,PROJECT_ID,REGION

local SQLite3 DB file

sec-gemini-byot --no-base-tools --dfir-sqlite=PATH_TO_FILE.DB

Once your session is established, you may simply prompt Sec-Gemini to perform a forensics investigation.

If you want Sec-Gemini to perform an unhinted investigation (i.e., operate in threat hunting mode), you may keep your prompt as simple as:

Perform a forensics investigation on the given logs.

an (approximate) incident time, e.g., 2026-05-06 13:00
a hostname
an account or username
a specific filename

For instance:

Perform a forensics investigation on the given logs.
An alert was triggered at 2026-05-06 13:00 on hostname "machine1234".

If you are using the SQLite3 DB logs backend and have more than one logs DB file, you must tell Sec-Gemini which one to use:

Perform a forensics investigation on the logs with ticket ID 12345.

Python SDK-based Investigation

To perform a digital forensics investigation via the Python SDK, you will need to explicitly run the BYOT client in a separate terminal to tunnel your local sec-gemini-mcp server to the cloud agent.

1. Start the Tunneling Client

In a separate terminal, run the BYOT client pointing to your local logs server:

uvx --from sec-gemini sec-gemini-byot --no-base-tools --mcp http://localhost:8000/sse

2. Run your Python SDK Script

Use the SDK to create a session, activate the byot tool tunnel, and prompt the agent in dfir mode:

import asyncio
from sec_gemini import SecGemini

async def main():
    async with SecGemini(api_key="YOUR_API_KEY") as client:
        session = await client.sessions.create()

        # Ensure the BYOT tool tunnel is active for this session
        await session.mcps.set(["byot"])

        # Enable the digital forensics engine by setting the mode to dfir
        await session.prompt(
            "Perform a forensics investigation on the given logs.",
            meta={"config.mode": "dfir"}
        )

        async for msg in session.messages.stream():
            msg_type = msg.get("message_type", "")
            content = msg.get("content", "")

            if msg_type == "MESSAGE_TYPE_RESPONSE":
                print(f"Agent: {content}")
            elif msg_type == "MESSAGE_TYPE_TOOL_CALL":
                print(f"  [tool] {msg.get('title', '')}")

asyncio.run(main())

🔑 Sec-Gemini API Key