Add timesketch-status to tsctl. (#3303)

Author: jaegeral

docs/guides/admin/admin-cli.md

@@ -508,6 +508,58 @@ Corresponding Timeline id: 3 in Sketch Id: 2
 Corresponding Sketch id: 2 Sketch name: asdasd
 ```
 
+### Timeline status
+
+The `tsctl timeline-status` command allows to get or set a timeline status.
+This can be useful in the following scenarios:
+
+* Monitoring processing In large-scale investigations, timelines can take a considerable amount of time to process.
+This feature allows administrators or automated scripts to monitor the processing status of timelines, ensuring that they are progressing as expected.
+
+* Automated Status updates: Scripts can be used to automatically update the status of timelines based on the results of automated analysis or processing steps. For example, if an automated script detects a critical error during analysis, it can set the timeline status to "fail."
+
+* Toubeshooting and Error handling: 
+** Quickly identifying timelines with a "fail" status allows investigators to troubleshoot issues and re-process data if necessary.
+** By monitoring the status of timelines, administrators can identify potential bottlenecks or errors in the processing pipeline.
+** Set the status to `fail` is a task is stuck.
+
+Usage:
+
+```bash
+tsctl timeline-status [OPTIONS] TIMELINE_ID
+--action [get|set]
+        Specify whether to get or set the timeline status.
+        - "get": Retrieves the current status of the timeline.
+        - "set": Sets the status of the timeline to the value specified by "--status".
+        (Required)
+
+    --status [ready|processing|fail]
+        The desired status to set for the timeline.
+        This option is only valid when "--action" is set to "set".
+        Valid options are:
+        - "ready": Indicates that the timeline is ready for analysis.
+        - "processing": Indicates that the timeline is currently being processed.
+        - "fail": Indicates that the timeline processing failed.
+        (Required when --action is set to set)
+```
+
+Examples:
+```bash
+# Get the status of timeline with ID 123:
+    tsctl timeline-status --action get 123
+
+    # Set the status of timeline with ID 456 to "ready":
+    tsctl timeline-status --action set --status ready 456
+
+    # Set the status of timeline with ID 789 to "fail":
+    tsctl timeline-status --action set --status fail 789
+
+    # Try to set a status without the action set to set.
+    tsctl timeline-status --status fail 789
+    # This will fail and display an error message.
+```
+
+
 ### Sigma
 
 #### List Sigma rules

timesketch/tsctl.py

@@ -574,6 +574,7 @@ def sketch_info(sketch_id):
                 "created_at",
                 "user_id",
                 "description",
+                "status",
             ],
         ]
 
@@ -585,9 +586,9 @@ def sketch_info(sketch_id):
                     t.created_at,
                     t.user_id,
                     t.description,
+                    t.status[0].status,
                 ]
             )
-
         print_table(table_data)
 
         print("Shared with:")
@@ -619,6 +620,73 @@ def sketch_info(sketch_id):
         print_table(status_table)
 
 
+@cli.command(name="timeline-status")
+@click.argument("timeline_id")
+@click.option(
+    "--action",
+    default="get",
+    type=click.Choice(["get", "set"]),
+    required=False,
+    help="get or set timeline status.",
+)
+@click.option(
+    "--status",
+    required=False,
+    type=click.Choice(["ready", "processing", "fail"]),
+    help="get or set timeline status.",
+)
+def timeline_status(timeline_id, action, status):
+    """Get or set a timeline status
+
+    If "action" is "set", the given value of status will be written in the status.
+
+    Args:
+        action: get or set timeline status.
+        status: timeline status. Only valid choices are ready, processing, fail.
+    """
+    if action == "get":
+        timeline = Timeline.query.filter_by(id=timeline_id).first()
+        if not timeline:
+            print("Timeline does not exist.")
+            return
+        # define the table data
+        table_data = [
+            [
+                "searchindex_id",
+                "index_name",
+                "created_at",
+                "user_id",
+                "description",
+                "status",
+            ],
+        ]
+        table_data.append(
+            [
+                timeline.searchindex_id,
+                timeline.searchindex.index_name,
+                timeline.created_at,
+                timeline.user_id,
+                timeline.description,
+                timeline.status[0].status,
+            ]
+        )
+        print_table(table_data)
+    elif action == "set":
+        timeline = Timeline.query.filter_by(id=timeline_id).first()
+        if not timeline:
+            print("Timeline does not exist.")
+            return
+        # exit if status is not set
+        if not status:
+            print("Status is not set.")
+            return
+        timeline.set_status(status)
+        db_session.commit()
+        print(f"Timeline {timeline_id} status set to {status}")
+        # to verify run:
+        print(f"To verify run: tsctl timeline-status {timeline_id} --action get")
+
+
 @cli.command(name="validate-context-links-conf")
 @click.argument("path")
 def validate_context_links_conf(path):