Skip to content

Admin CLI

tsctl

tsctl is a command-line tool for managing and interacting with a Timesketch instance. It allows users to create and delete sketches, add and remove data sources, manage users and groups, and perform various other tasks.

Its commands can be accessed by running tsctl followed by the desired subcommand. For example, to list all the available sketches in a Timesketch instance, tsctl list-sketches can be run.

Config

The --config parameter in tsctl is used to specify the location of a configuration file that contains settings for tsctl. This configuration file can specify default values for various tsctl options, such as the hostname and port of the Timesketch server, the username and password to use when authenticating with the server, and other settings.

Parameters:

--config / -c (optional)

Example

tsctl run -c /etc/timesketch/timesketch.conf

version

Displays the version of Timesketch installed on the system

Example

tsctl version
Timesketch version: 20210602

info

Displays various useful version information used on the system Timesketch is installed on.

Example

tsctl info
Timesketch version: 20210602
plaso - psort version 20220930
Node version: v14.20.1
npm version: 6.14.17
yarn version: 1.22.19
Python version: Python 3.10.6
pip version: pip 22.0.2 from /usr/lib/python3/dist-packages/pip (python 3.10)

User management

Adding users

tsctl provides a subcommand for creating users in a Timesketch instance. This subcommand is called create-user, and it allows you to specify the username, password, and other details for the user you want to create.

To use the create-user subcommand, you would run tsctl create-user followed by the desired options and arguments. For example, to create a user with the username "john" and the password "123456", you could run the following command: tsctl create-user --username john --password 123456.

Once the user is created, they will be able to log in to the Timesketch instance using their username and password. You can then use the list-users subcommand to verify that the user was created successfully.

Command:

tsctl create-user

Parameters:

--name / -n
--password / -p (optional)

Example

tsctl create-user foo

Change user password

To change a user password, the create-user command can be used, as it is checking if the user exists if yes it will update the update.

This command would change the password of the user with the specified username to the new password provided. The user will then be able to log in to the Timesketch instance using their new password.

Command:

tsctl create-user

Parameters:

--username / -u
--password / -p (optional)

Example

tsctl create-user foo

Removing users

tsctl provides a subcommand for disabling users in a Timesketch instance. This subcommand is called disable-user, and it allows you to specify the username or user ID of the user you want to disable.

To use the disable-user subcommand, you would run tsctl disable-user followed by the desired options and arguments. For example, to disable a user with the username "john", you could run the following command: tsctl disable-user john.

This command would disable the user with the specified username, preventing them from logging in to the Timesketch instance. However, their user account will still exist in the system, and you can use the enable-user subcommand to re-enable their account at any time.

Disabled users are not removed from the system, but marked as disabled. The current implementation is not complete. Disabled users will still show up for other commands.

Command:

tsctl disable_user
tsctl enable_user

Example

tsctl disable_user foo
tsctl enable_user foo

List users

tsctl provides a subcommand for listing the users in a Timesketch instance. This subcommand is called list-users, and it allows you to view a list of the users in the system, along with their username, user ID, and other details.

To use the list-users subcommand, you would run tsctl list-users followed by the desired options and arguments. For example, to list all the users in the Timesketch instance, you could run the following command: tsctl list-users.

This command would display a list of the users in the Timesketch instance, along with their username and other details.

Example

tsctl list-users
foo
bar
dev (admin)

Make admin

tsctl provides a subcommand for granting administrator privileges to a user in a Timesketch instance. This subcommand is called make-admin, and it allows you to specify the username of the user you want to grant administrator privileges to.

To use the make-admin subcommand, you would run tsctl make-admin followed by the desired options and arguments. For example, to grant administrator privileges to a user with the username "john", you could run the following command: tsctl make-admin john

This command would grant the user with the specified username administrator privileges.

Once a user has administrator privileges, they will be able to perform a wider range of tasks in the Timesketch instance. You can use the list-users subcommand to verify that the user has been granted administrator privileges successfully.

You can use tsctl revoke-admin to revoke admin privileges.

Revoke admin

tsctl provides a subcommand for revoking administrator privileges from a user in a Timesketch instance. This subcommand is called revoke-admin, and it allows you to specify the username of the user you want to revoke administrator privileges from.

To use the revoke-admin subcommand, you would run tsctl revoke-admin followed by the desired options and arguments. For example, to revoke administrator privileges from a user with the username "john", you could run the following command: tsctl revoke-admin john

This command would revoke the administrator privileges of the user with the specified username.

Once a user's administrator privileges are revoked, they will no longer be able to perform tasks that require administrator privileges in the Timesketch instance. You can use the list-users subcommand to verify that the user's administrator privileges have been revoked successfully.

Group management

Adding groups

tsctl provides a subcommand for adding groups in a Timesketch instance. This subcommand is called add-group, and it allows you to specify the name and description of the group you want to add.

To use the add-group subcommand, you would run tsctl add-group followed by the desired options and arguments. For example, to add a group called "analysts" with the description "Group for analysts", you could run the following command: tsctl add-group --name analysts --description "Group for analysts" This command would create a new group with the specified name and description. Once the group is created, you can use the list-groups subcommand to verify that the group was added successfully.

You can also use the add-user-to-group subcommand to add users to the group you have created. This allows you to manage the members of the group, and control which users have access to the sketches and data sources associated with the group.

Command:

tsctl add_group

Parameters:

--name / -n

Removing groups

Not yet implemented.

Managing group membership

Add a suer to a group

tsctl provides a subcommand for adding users to a group in a Timesketch instance. This subcommand is called add-group-member, and it allows you to specify the username of the user you want to add to the group, as well as the name of the group you want to add the user to.

To use the add-group-member subcommand, you would run tsctl add-group-member followed by the desired options and arguments. For example, to add a user with the username "john" to a group called "analysts", you could run the following command: tsctl add-group-member --username john --group-name analysts. This command would add the user with the specified username to the group with the specified name.

Once the user is added to the group, they will be able to access the sketches and data sources associated with the group, based on the permissions granted to the group. You can use the list-groups subcommand to verify that the user was added to the group successfully.

Command:

tsctl add-group-member

Example:

tsctl add-group-member --username john --group-name analysts
Removing a group member

tsctl provides a subcommand for removing users from a group in a Timesketch instance. This subcommand is called remove-group-member, and it allows you to specify the username of the user you want to remove from the group, as well as the name of the group you want to remove the user from.

To use the remove-group-member subcommand, you would run tsctl remove-group-member followed by the desired options and arguments. For example, to remove a user with the username "john" from a group called "analysts", you could run the following command: tsctl remove-group-member --username john --group-name analysts

This command would remove the user with the specified username from the group with the specified name.

Once the user is removed from the group, they will no longer be able to access the sketches and data sources associated with the group. You can use the list-groups subcommand to verify that the user was removed from the group successfully.

Command:

tsctl remove-group-member

Example:

tsctl remove-group-member --username john --group-name analysts

add_index

Create a new Timesketch searchindex.

Command:

tsctl add_index

Parameters:

--name / -n
--index / -i
--user / -u

Example:

tsctl add_index -u user_foo -i test_index_name -n sample

routes

tsctl provides a subcommand for displaying the available API routes in a Timesketch instance. This subcommand is called routes, and it allows you to view a list of the API routes that are available in the Timesketch instance, along with their URL and description.

To use the routes subcommand, you would run tsctl routes followed by the desired options and arguments. For example, to list all the available API routes in the Timesketch instance, you could run the following command: tsctl routes. This command would display a list of the available API routes in the Timesketch instance, along with their URL and description.

Example:

tsctl routes
Endpoint                           Methods            Rule
---------------------------------  -----------------  -------------------------------------------------------------------------
aggregationexploreresource         POST               /api/v1/sketches/<int:sketch_id>/aggregation/explore/

db

tsctl provides a subcommand for managing the database in a Timesketch instance. This subcommand is called db, and it allows you to perform various operations on the Timesketch database, such as creating the database tables, initializing the database schema, and migrating the database to the latest version.

To use the db subcommand, you would run tsctl db followed by the desired options and arguments. For example, to initialize the database schema in the Timesketch instance, you could run the following command: tsctl db init

Command:

tsctl db

Example

tsctl db --help
Usage: tsctl db [OPTIONS] COMMAND [ARGS]...

  Perform database migrations.

Options:
  --help  Show this message and exit.

Commands:
  branches   Show current branch points
  current    Display the current revision for each database.
  downgrade  Revert to a previous version
  edit       Edit a revision file
  heads      Show current available heads in the script directory
  history    List changeset scripts in chronological order.
  init       Creates a new migration repository.
  merge      Merge two revisions together, creating a new revision file
  migrate    Autogenerate a new revision file (Alias for 'revision...
  revision   Create a new revision file.
  show       Show the revision denoted by the given symbol.
  stamp      'stamp' the revision table with the given revision; don't...
  upgrade    Upgrade to a later version

Upgrade DB After Schema Change

After changing the schema for the database a revision file needs to be generated.

(temporary solution) Before doing the database migration you'll need to modify the file timesketch/models/__init__.py:


def init_db():
...
        BaseModel.metadata.create_all(bind=engine)

This line needs to be commented out, eg:


def init_db():
...
        #BaseModel.metadata.create_all(bind=engine)

Then inside the timesketch container, to generate the file use the command:

cd /usr/local/src/timesketch/timesketch
tsctl db stamp head
tsctl db upgrade

This makes sure that the database is current. Then create a revision file:

tsctl db migrate -m "<message>"

Once the migration is done, remove the comment to re-enable the line in timesketch/models/__init.py.

Troubleshooting Database Schema Changes

If the migration file is not created, which could be an indication that the schema change is not detected by the automation one can create an empty revision file:

tsctl db revision

And then fill in the blanks, see examples of changes in timesketch/migrations/versions/*_.py.

Drop database

Will drop all databases.

Command:

tsctl drop_db

search_template

Export/Import search templates to/from file.

Command:

tsctl search_template

Parameters:

--import / -i
--export / -e

import_location: Path to the yaml file to import templates. export_location: Path to the yaml file to export templates.

import

Creates a new Timesketch timeline from a file. Supported file formats are: plaso, csv and jsonl.

Command:

tsctl import

Parameters:

--file / -f
--sketch_id / -s      (optional)
--username / -f       (optional)
--timeline_name / -n  (optional)

The sketch id is inferred from the filename if it starts with a number. The timeline name can also be generated from the filename if not specified.

similarity_score

Command:

tsctl similarity_score

Sketch

sketch-info Get information about a sketch

Displays verious information about a given sketch.

tsctl sketch-info

Example:

tsctl sketch-info 1
Sketch 1 Name: (Sketch Title)
active_timelines:
+----------------+----------------------------------+----------------------------+---------+---------------------------------------+
| searchindex_id |            index_name            |         created_at         | user_id |              description              |
+----------------+----------------------------------+----------------------------+---------+---------------------------------------+
|       1        | a17732074d8b492e934ef79910bfefa1 | 2022-10-21 15:06:52.849124 |    1    |     20200918_0417_DESKTOP-SDN1RPT     |
|       3        | 88002da782f64061bf3703bc782b6006 | 2022-10-21 15:19:26.072964 |    1    |              all_packets              |
|       1        | a17732074d8b492e934ef79910bfefa1 | 2022-10-21 15:28:55.474166 |    1    |     E01-DC01_20200918_0347_CDrive     |
|       4        | 11d761cd266640d798e30bb897c8dd4e | 2022-10-21 15:32:15.060184 |    1    | autoruns-desktop-sdn1rpt_fresh_import |
|       3        | 88002da782f64061bf3703bc782b6006 | 2022-10-31 10:15:12.316273 |    1    |              sigma_events             |
|       3        | 88002da782f64061bf3703bc782b6006 | 2022-10-31 10:15:48.592320 |    1    |             sigma_events2             |
+----------------+----------------------------------+----------------------------+---------+---------------------------------------+
Shared with:
    Users (user-id: username):
        3: bar
    Groups:
        user-group
Sketch Status: new
Sketch is public: True
Sketch Labels: ([],)
Status:
+----+--------+----------------------------+---------+
| id | status |         created_at         | user_id |
+----+--------+----------------------------+---------+
| 1  |  new   | 2022-10-21 15:04:59.935504 |   None  |
+----+--------+----------------------------+---------+

Sigma

List Sigma rules

Lists all Sigma rules installed on a system

tsctl list-sigma-rules

Add Sigma rules in a folder

Will add all Sigma rules in a folder and its subfolders to the databse.

tsctl import-sigma-rules sigma/rules/cloud/gcp/
Importing: Google Cloud Kubernetes RoleBinding
Importing: Google Cloud Storage Buckets Modified or Deleted
Importing: Google Cloud VPN Tunnel Modified or Deleted
Importing: Google Cloud Re-identifies Sensitive Information
...

Export Sigma rules

Will export all Sigma rules to a folder.

tsctl export-sigma-rules ./test
13 Sigma rules exported

Remove a Sigma rule

This will remove a single Sigma rule from the databse

tsctl remove-sigma-rule 13f81a90-a69c-4fab-8f07-b5bb55416a9f
Rule 13f81a90-a69c-4fab-8f07-b5bb55416a9f deleted

Drop all Sigma rules

Will drop all Sigma rules from database.

Command:

tsctl remove-all-sigma-rules
Do you really want to drop all the Sigma rules? [y/N]: y
Are you REALLLY sure you want to DROP ALL the Sigma rules? [y/N]: y
All rules deleted

Shell

tsctl provides a subcommand for starting an interactive Python shell with the Timesketch API client pre-initialized. This subcommand is called shell, and it allows you to access the Timesketch API and perform various operations using the Python interpreter.

To use the shell subcommand, you would run tsctl shell followed by the desired options and arguments. For example, to start an interactive Python shell with the Timesketch API client pre-initialized, you could run the following command: tsctl shell.

We can use tsctl to test the yaml config file for the context link feature. This is especially useful if an entry that is added to the configuration file does not show up as a context link in the frontend.

tsctl validate-context-links-conf <PATH TO CONFIG FILE>

The default config can be found at data/context_links.yaml .

The output will tell if there is a value not matching the schema requirements:

No error: All entries in the configuration file match the schema requirements.

$ tsctl validate-context-links-conf ./context_links.yaml
=> OK: "virustotal"
=> OK: "unfurl"
=> OK: "mseventid"
=> OK: "urlhaus"

With an error: Here the validator tells us that there is an error with the replacement pattern in the context_link entry.

$ tsctl validate-context-links-conf ./context_links.yaml
=> ERROR: "virustotal" >> 'https://www.virustotal.com/gui/search/<ATTR_VALUE' does not match '<ATTR_VALUE>'

Failed validating 'pattern' in schema['properties']['context_link']:
    {'pattern': '<ATTR_VALUE>', 'type': 'string'}

On instance['context_link']:
    'https://www.virustotal.com/gui/search/<ATTR_VALUE'

=> OK: "unfurl"
=> OK: "mseventid"
=> OK: "urlhaus"