Taranis AI Documentation

1 - Getting Started

Developers

See docker/dev for instructions on how to start at dev setup.

1.1 - Deployment

Install from stable release

curl -fsSL https://taranis.ai/install.sh | bash

Clone via git

git clone --depth 1  https://github.com/taranis-ai/taranis-ai
cd taranis-ai/docker/

Configuration

Copy env.sample to .env

cp env.sample .env

Open .env and change the defaults before exposing the instance on a network. More details about environment variables can be found in the docker README.

Redis and worker queues

Taranis AI uses Redis and RQ for worker queues, scheduled jobs, and frontend cache storage.

The Compose deployment wires Redis into core, frontend, collector, cron, and workers. If queued jobs are accepted but not processed, verify that Redis is reachable and at least one worker container is running.

See Background Jobs for Redis/RQ architecture, health checks, scheduled jobs, and upgrade notes.

LLM bot settings

The Compose deployment includes the optional llm-bot service for LLM-backed summaries, title generation, NER, clustering, and sentiment.

See LLM Bot Service for endpoint mapping and bot configuration.

Images and tags

Taranis AI images are tagged as follows:

• Official release version number (e.g. 1.1.7)
• Every official image release comes with an extra stable tag, in case pinning the release is not favourable (stable)
• Latest tag for tracking the latest uploaded image, there is no guarantee this is an officially released image (latest)

See Internal TLS Configuration for setting up TLS encryption and Advanced monitoring for more logging insights. For detailed information about container tags, release strategy, and deployment recommendations, see Releases and Container Tags.

Startup & Usage

Pull the configured release images before starting or upgrading:

docker compose pull

Start the application:

docker compose up -d

Verify readiness:

curl -fsS http://<url>:<TARANIS_PORT>/api/health
docker compose ps

Use the application:

http://<url>:<TARANIS_PORT>/login

Initial Setup

The default credentials are user / user and admin / admin. Change them before production use.

The passwords for these two default users can be overridden by setting the environment variables PRE_SEED_PASSWORD_ADMIN or PRE_SEED_PASSWORD_USER before first launch. Afterwards they are stored in the database in the user table.

For existing database-auth users, passwords and role assignments can be repaired with the operational CLI. See User Management.

Open http://<url>:<TARANIS_PORT>/config/sources and click load default sources to import the default sources from: default_sources.json

Or import a source export via the Import.

1.2 - Kubernetes deployment

Configuration

Clone via git

git clone --depth 1  https://github.com/taranis-ai/taranis-ai
cd taranis-ai/docker/

Copy env.sample to .env

cp env.sample .env

Open file .env and change defaults if needed. More details about environment variables can be found here.

See Internal TLS Configuration for setting up TLS encryption and Advanced monitoring for more logging insights. See Releases and Container Tags for information about container image versions, Internal TLS Configuration for setting up TLS encryption, and Advanced monitoring for more logging insights.

Convert via Kompose

Download and install kompose.io

# resovle variables from .env into taranis-ai/docker/compose.yml 
docker compose config > resolved-compose.yml

# convert compose file to kubernetes 
kompose --file resolved-compose.yaml convert

MultiDB SQLAlchemy

If you want to connect to a kubernetes cluster you can do something like this:

kubectl create ns db
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

helm install pg-ha bitnami/postgresql-ha -n db \
  --set postgresql.username=app \
  --set postgresql.password=apppass \
  --set postgresql.database=appdb \
  --set pgpool.adminUsername=pgpool \
  --set pgpool.adminPassword=pgpoolpass \
  --set postgresql.replicaCount=2

kubectl -n db port-forward statefulset/pg-ha-postgresql 54321:5432 &
kubectl -n db port-forward pod/pg-ha-postgresql-1 54322:5432 &

And then connect with:

SQLALCHEMY_DATABASE_URI="postgresql+psycopg://app:apppass@/appdb?host=127.0.0.1,127.0.0.1&port=54321,54322&target_session_attrs=read-write&connect_timeout=3"

1.3 - Releases and Container Tags

Tags

Taranis AI publishes container images to GitHub Container Registry (ghcr.io) with different tagging strategies for core services and bots.

All images are available at GitHub Container Registry.

For Core Services (core, gui, worker, frontend)

Core Taranis AI services follow a stable and tested release process:

For Bots

Bot containers follow a similar release process, with versions decoupled from the core Taranis AI services:

1.4 - Requirements

For the best experience using Taranis AI, we recommend that your system meet the following requirements:

System Requirements

Note: The recommended requirements assume that all bots are active concurrently. You can estimate the requirements for running only some of the bots from this table:

You can assume the number of CPUs and RAM to be cumulative, so for running two bots concurrently, sum up the required number of CPUs and RAM. Reserve an additional 2 CPUs and 2 GB RAM for normal system operation.

Example: For running story-clustering and NER bots at the same time, your system should have 6 CPUs and 10.5 GB of RAM.

GPU Acceleration (Coming Soon)

GPU support for accelerating bot performance will be available soon. Further details and configuration options will be provided once this feature is launched.

Recommended Setup

• Display: Full HD (1920×1080) or higher
• Supported Browsers:
  • Chromium
  • Mozilla Firefox
  • Microsoft Edge

1.5 - Background Jobs

Taranis AI uses Redis and RQ for background work. Collection, bots, presenters, publishers, connectors, and maintenance jobs are queued by core and processed by worker containers.

Services

Queues are split by worker category: collectors, bots, presenters, publishers, connectors, and misc.

Redis settings

Set a Redis password for production and keep Redis private to the Compose or Kubernetes network.

Do not publish the Redis port unless you have a controlled operational reason.

Health checks

Core exposes:

GET /api/health

The response reports database, seed_data, broker, and workers. If Redis is up but no workers are connected, queued jobs can be accepted but will not run until a worker starts.

Example degraded response:

{
  "healthy": false,
  "services": {
    "database": "up",
    "seed_data": "up",
    "broker": "up",
    "workers": "down"
  }
}

When workers is down, check the collector, workers, and cron containers or deployments first, then inspect worker logs for bad WORKER_TYPES, invalid API keys, Redis authentication failures, or failed bot service calls.

Scheduled jobs

Collectors and bots use cron-like schedules. Core stores managed schedule definitions in Redis, and the cron service reconciles those definitions with enabled sources and bots. Changing a collector or bot schedule does not require restarting the workers.

The worker admin views show queued, active, failed, and scheduled jobs. Use them before clearing queues so you know what work will be lost.

Upgrade note

Taranis AI 1.4.0 replaced Celery/RabbitMQ with Redis/RQ. There is no queue handover from Celery to RQ. Before upgrading an older deployment, let running Celery jobs finish, stop the old workers, then deploy the Redis, collector, workers, and cron services together.

1.6 - LLM Bot Service

llm-bot is an optional HTTP service used by worker bots for LLM-backed analysis. The Compose deployment includes it as ghcr.io/taranis-ai/taranis-llm-bot:${TARANIS_BOT_TAG:-stable}.

It talks to an OpenAI-compatible Responses API and exposes endpoints for:

Compose configuration

Set these values in docker/.env:

Advanced optional settings:

Keep LLM_API_KEY, BOT_API_KEY, and any provider credentials out of logs and shared files. The service should stay on the private application network; do not publish it directly to the internet.

Worker integration

The Compose deployment wires these worker endpoints to llm-bot by default:

Bot endpoint parameters saved in the admin UI take precedence over worker defaults. If an upgraded instance still has old standalone bot hostnames such as http://summary_bot:8000, http://nlp_bot:8000, or http://story_bot:8000, update those bot parameters to the llm-bot endpoints or clear the override.

For title generation, set TITLE_ENDPOINT on the Summary Bot to:

http://llm-bot:8000/title

For sentiment analysis, set the Sentiment Analysis Bot BOT_ENDPOINT to:

http://llm-bot:8000/sentiment

Each bot can override the default endpoint and timeout with its own parameters. See Bots for the user-facing bot settings.

Canonical llm-bot paths are accepted with or without a trailing slash.

Validation

Check service health from inside the application network:

curl http://llm-bot:8000/health

If API_KEY is configured on the service, protected task endpoints require:

Authorization: Bearer <BOT_API_KEY>

Use /info to confirm endpoint paths and non-secret feature settings. It reports whether lookup and linking are configured without exposing API keys.

1.7 - Maintenance

Standard image upgrade

Use published images for deployment upgrades. Do not build application images on production hosts unless you are intentionally testing a custom build.

cd taranis-ai/docker
docker compose pull
docker compose up -d
curl -fsS http://<url>:<TARANIS_PORT>/api/health
docker compose ps

For rollback, pin TARANIS_TAG and TARANIS_BOT_TAG to the previous known-good release in .env, pull, restart, and verify /api/health again.

Redis/RQ migration

Taranis AI 1.4.0 replaced Celery/RabbitMQ with Redis/RQ. There is no queue handover from old Celery workers to the new RQ workers.

Before upgrading an older deployment:

1. Let running and queued Celery jobs finish.
2. Stop old Celery/RabbitMQ services.
3. Deploy Redis plus the collector, workers, and cron services.
4. Verify /api/health reports database, seed data, broker, and workers as up.

See Background Jobs for the current worker architecture.

PostgreSQL 14 to 17

Supported upgrade of PostgreSQL 14.x to PostgreSQL 17.x. Expect Taranis AI downtime during the database upgrade.

Prerequisites

• Installed Docker Compose V2 or podman-compose
• Running Taranis AI deployment using the docker/compose.yml file.
• Running database PostgreSQL of major version 14
• Compose file (docker/compose.yml) is setup to use the image of PostgreSQL 17 (check your POSTGRES_TAG variable in the .env file)

Steps to upgrade

1. Go to directory: taranis-ai/docker
2. Ensure the script upgrade-database.sh is executable
3. Run the script: ./upgrade-database.sh

All containers should now be up and running again. Verify /api/health and review database logs before handing the instance back to users.

1.8 - Advanced monitoring

Prerequisites

• Sentry instance available, either SaaS or self-hosted.
• Follow this guide to have a Sentry project (and SENTRY_DSN) ready.

What is Sentry

Sentry is a monitoring tool that enables more insights about an application. Taranis AI takes advantage of this if you enable it at the start up.

What is there to monitor

Sentry can be used to monitor insights about GUI, Core and database. In Taranis AI: Issues, Traces, Profiles and Queries can be tracked.

Health and worker queues

The core service exposes /api/health for readiness and dependency checks. It reports the database, seed data, Redis broker, and worker status when those services are available.

Worker-backed actions such as collecting an OSINT source, running a bot, gathering a word list, rendering a product, or publishing a product can be queued even when no workers are connected. In that case the frontend shows a warning that the task was queued but may not be processed until a worker starts.

If this warning appears:

1. Verify Redis with the configured REDIS_URL and REDIS_PASSWORD.
2. Verify that the collector, cron, and workers containers or Kubernetes deployments are running.
3. Check the worker logs for failed startup, invalid WORKER_TYPES, or authentication errors against core.
4. Use the admin worker and queue views to inspect queued, active, failed, and scheduled jobs.

See Background Jobs for worker services, queues, scheduler behavior, and Redis/RQ upgrade notes.

How to enable Sentry in Taranis AI

To enable Sentry, set the SENTRY_DSN variables in the .env file before start of the application. More details about environment variables can be found here.

GUI monitoring

To gain insights about GUI, use the TARANIS_GUI_SENTRY_DSN variable and set it to your Sentry DSN address.

Core and database monitoring

To gain insights about Core and database, use the TARANIS_CORE_SENTRY_DSN variable and set it to your Sentry DSN address.

1.9 - TLS Configuration

This guide explains how to configure TLS (Transport Layer Security) for Taranis AI using the Granian ASGI server. TLS provides encrypted communication between clients and the server, essential for secure deployments.

Key Environment Variables

The primary TLS configuration is handled through Granian environment variables:

Required TLS Variables

For a basic TLS setup, configure these environment variables:

# SSL Certificate file path
GRANIAN_SSL_CERTIFICATE=/path/to/your/certificate.pem

# SSL Private key file path  
GRANIAN_SSL_KEYFILE=/path/to/your/private_key.pem

# Turn off verification of self-signed certificates in Frontend and Worker service
SSL_VERIFICATION=False

DISABLE_SSE=True

When enabling TLS, you must also update the core URL to use HTTPS:

# Update the core API URL to use HTTPS
TARANIS_CORE_URL=https://your-domain.com/api

This variable affects multiple components:

• Frontend service: Uses TARANIS_CORE_URL to communicate with the core API
• Worker service: Uses TARANIS_CORE_URL for API communication (falls back to http://{TARANIS_CORE_HOST}{TARANIS_BASE_PATH}api if not set)
• GUI service: Configured via TARANIS_CORE_API in config.json

Optional TLS Variables

More Granian environmental variables that affect SSL are derived from the CLI options prefixed with --ssl-*.

Examples:

GRANIAN_SSL_KEYFILE_PASSWORD
GRANIAN_SSL_CA
GRANIAN_SSL_CRL
GRANIAN_SSL_CLIENT_VERIFY

Make sure, all variables are properly set in the compose file. The variable SSL_VERIFICATION can be set for the frontend and worker service.

Docker Compose Configuration

Important Configuration Notes

1. Certificate Mounting: Certificates mounted as read-only (./certs:/certs:ro)
2. SSL Verification: Self-signed certificates cause problems (SSL_VERIFICATION=False)
3. Health Checks: To work properly they need to be changed to https:// prefix. Moreover, the Certificate Authority needs to be added into the container’s trust store by mounting it under /usr/local/share/… Read more at docker.com.

Basic TLS Setup

Here’s an example Docker Compose configuration with TLS enabled:

services:
  core:
    image: ghcr.io/taranis-ai/taranis-core:latest
    environment:
      # TLS configuration (paths must match the mounted cert directory)
      - GRANIAN_SSL_CERTIFICATE=/certs/certificate.pem
      - GRANIAN_SSL_KEYFILE=/certs/private_key.pem

      - TARANIS_CORE_URL=https://your-domain.com/api
      - DB_URL=database
      - DB_DATABASE=taranis
      - DB_USER=taranis
      - DB_PASSWORD=supersecret
      - API_KEY=your-secure-api-key
      - JWT_SECRET_KEY=your-secure-jwt-secret

    volumes:
      # Mount local certificate directory into the container
      - ./certs:/certs:ro
      - core_data:/app/data

    depends_on:
      - database
      - rabbitmq

    ports:
      - "8443:8080"

    networks:
      - taranis_network

    healthcheck:
      test: ["CMD-SHELL", "curl --fail https://localhost:8080/api/health || exit 1"]
      interval: 90s
      timeout: 30s
      retries: 5
      start_period: 40s

volumes:
  core_data:

networks:
  taranis_network:
    driver: bridge

Kubernetes Configuration

For Kubernetes deployments, configure TLS using ConfigMaps and Secrets:

# TLS Secret
apiVersion: v1
kind: Secret
metadata:
  name: taranis-tls
type: kubernetes.io/tls
data:
  tls.crt: <base64-encoded-certificate>
  tls.key: <base64-encoded-private-key>

---
# Core Deployment with TLS
apiVersion: apps/v1
kind: Deployment
metadata:
  name: taranis-core
spec:
  replicas: 1
  selector:
    matchLabels:
      app: taranis-core
  template:
    metadata:
      labels:
        app: taranis-core
    spec:
      containers:
      - name: core
        image: ghcr.io/taranis-ai/taranis-core:latest
        env:
        - name: GRANIAN_SSL_CERTIFICATE
          value: "/certs/tls.crt"
        - name: GRANIAN_SSL_KEYFILE
          value: "/certs/tls.key"
        - name: TARANIS_CORE_URL
          value: "https://your-domain.com/api"
        - name: API_KEY
          valueFrom:
            secretKeyRef:
              name: taranis-secrets
              key: api-key
        - name: JWT_SECRET_KEY
          valueFrom:
            secretKeyRef:
              name: taranis-secrets
              key: jwt-secret
        volumeMounts:
        - name: tls-certs
          mountPath: /certs
          readOnly: true
      volumes:
      - name: tls-certs
        secret:
          secretName: taranis-tls

1.10 - Additional References

Create intelligence and share with MISP

Corrensponds to Taranis release 1.2.4

General workflow video

2 - Omnisearch

Omnisearch is the global search field in the top navigation. It is useful for quick lookup across the analyst workflow and for jumping directly into filtered list views.

Scope search

An unqualified search shows grouped results for Stories, Reports, and Products. Use a scope prefix to search only one area and open its list view directly:

story: ransomware
report: weekly
product: stix

Supported aliases:

report:true and report:false are reserved for Assess filtering. If you need to find a Report literally named true or false, use an unqualified global search.

Assess filter syntax

Omnisearch can translate Assess-style filter tokens into the Assess sidebar query parameters. Tokens can be combined with free text:

story: source:"CERT.at" tag:ransomware read:false important:true range:last7 sort:updated_desc

Supported Assess tokens:

Quote values that contain spaces. Omnisearch suggestions are loaded only when the query needs them, so normal global searches do not require loading every Assess filter list.

Saved filters

Assess sidebar filters can be saved per user. One saved filter can be marked as the default, which makes /assess open that filtered queue automatically. Use /assess?reset=true to bypass the default and show the unfiltered list.

Saved filters also appear as dashboard shortcuts, so common queues such as “Unread important stories” can be opened without rebuilding the filter each time. See Filter Lists and Saved Filters.

3 - Assess

• Description
• Functionalities

Description

Assess is the analyst queue for collected Stories and News Items. It supports search, filtering, sorting, merging, bookmarks, report assignment, connector sharing, and review state changes.

Functionalities

Search

Use the Assess sidebar search for Story text search inside the current Assess view. Use the global Omnisearch field to search across Stories, Reports, and Products, or to open Assess with filter tokens such as:

story: source:"CERT.at" tag:ransomware read:false range:last7

Filters

Details:

• First Day: The Story’s creation date, typically matching the oldest News Item’s “published date.”
• Last Day: The Story’s update date, usually reflecting the latest addition or change.

For manually created stories, the “updated” timestamp is essentially the creation time. As a result, filtering by Last day for a manually created story will not return it, even if an older “published date” is set.

Assess filters include search text, source, source group, tag, language, read state, important state, report membership, relevance, cybersecurity classification, changed-by actor, date range, and sort order.

Users can save the current Assess filters from the Saved filters button. A saved filter can be marked as the default for the user profile. Dashboard shortcuts show saved Assess filters so frequently used queues can be opened directly. See Filter Lists and Saved Filters.

Items

News items collected by Collectors become visible in Assess. They can be grouped into Stories automatically by Bots or manually by analysts.

Detail view:

• Relevance of item/aggregate can be changed with “up/down” buttons

Charts:

• Each item displays a chart if data has been aggregated in the last 7 days.
• Line and bar chart display the same data, which is the accumulation of items per day.
• The y-axis of the line chart can be adapted and is the same for all charts in the current items list. Therefore, charts can be compared properly.

Story actions include marking read/unread, marking important, sharing to connectors, ungrouping, version history, deleting, editing, adding to reports, and bookmarking. Bulk actions are available after selecting stories; visible shortcuts include Shift+R for adding to a report and Shift+B for bookmarking.

Story import

Stories can be created manually or imported from JSON. Imports are useful for transferring data between Taranis AI instances or restoring exported analyst work.

Use metadata-free story exports for normal re-imports. Metadata-rich exports include internal tags, attributes, votes, relevance, and similar state; clean those fields before importing them into another instance unless you deliberately want to carry that state over.

Version history

Stories keep a revision history. Use Version History from the Story actions menu to inspect saved revisions and compare the changes between adjacent revisions. Revision diffs are intended for audit and troubleshooting; they do not currently provide rollback.

Bookmarks

Bookmark collections are private per user. A story can be bookmarked from its action menu, or selected stories can be added to an existing or new collection from the Assess toolbar. If a user bookmarks a single story before creating any collections, Taranis AI creates a default collection named Bookmarks.

The Assess page shows up to six bookmark collections in a compact bar. Use All bookmarks to open the full bookmark page, rename or delete collections, reorder them, and remove stories from a collection. Removing a story from a bookmark collection does not delete the story from Assess. See Bookmarks.

Story Edit Advanced View

The Story Edit view can expose AI assisted actions when advanced story options are enabled in user settings. Available actions include generating a summary and title, and running sentiment analysis. When sentiment attributes are present, the advanced view shows the story sentiment status.

3.1 - Filter Lists and Saved Filters

Assess filter lists are the dynamic option lists behind the sidebar filters. They are built from the current data in Taranis AI and include Sources, Source Groups, Tags, and Languages.

Filter lists are not manually maintained lists. The core API exposes them through /api/assess/filter-lists, and the frontend may cache them per user. Assessment changes invalidate the cached filter lists so new Sources, Tags, and Languages become available without a restart.

Use the sidebar to combine:

• Search text and Tags.
• Time presets or exact date ranges.
• Sources and Source Groups.
• Languages.
• Read, Important, In Reports, and Relevance state.
• Changed by, Cybersecurity status, and Sort order.

Saved filters

Saved filters store the current Assess sidebar state in the user’s profile. They are private to the user and are useful for recurring queues such as shift review, unread important Stories, or language-specific monitoring.

Open Saved filters from the Assess sidebar. Saving requires at least one active filter. Saving with an existing saved-filter name updates it; saving duplicate filter criteria under another name is rejected.

One saved filter can be marked as the default. When a default exists, opening /assess without query parameters opens that queue automatically. Use /assess?reset=true to bypass the default and open the unfiltered Assess list.

Saved filters also appear as Dashboard shortcuts. Dashboard cards can be applied directly or deleted from the Dashboard.

3.2 - Bookmarks

Bookmarks let each user keep private collections of Stories without changing the Stories themselves. They are useful for follow-up queues, handovers, and temporary research sets.

From Assess

Use the Story action menu to bookmark one Story. If the user has no bookmark collections yet, Taranis AI creates a default collection named Bookmarks.

For bulk work, select Stories in Assess and use Bookmark in the toolbar. The dialog can add selected Stories to an existing collection or create a new collection.

The Assess list shows up to six bookmark collections in the bookmark bar. Use All bookmarks to open the full bookmarks page.

Bookmarks page

The bookmarks page supports:

• Creating a new collection.
• Opening a collection.
• Renaming a collection.
• Dragging collections to reorder them.
• Deleting a collection.

Deleting a bookmark collection only removes the collection. It does not delete the Stories from Assess.

Inside a collection, select Stories and use Remove selected to remove them from that collection. Story access still follows the user’s normal permissions and TLP visibility.

4 - Analyze

• Description
• Functionalities
• Screenshots

Description

Analyze is where analysts create and maintain Reports. Report fields are defined by administrator-managed Report Types, and Reports can collect Stories from Assess before they are rendered into Products.

Functionalities

CRUD

• Create: Reports can be created for any available Report Type.
• Read & Update: Reports can be opened, edited, completed, and connected to Stories from Assess.
• Clone: Existing Reports can be cloned when a new report should start from the same structure.
• Delete: One or multiple Reports can be deleted at once.

Report editor

The report editor supports split and stacked layouts. The Report Type is selected when the Report is created; after creation, its configured attributes are shown in the editor.

Reports can contain multiple Stories. Stories added from Assess appear in the report editor and can be removed before the report is rendered.

Product handoff

Use Publish in the report editor to open an existing Product or create a new Product prefilled with the current Report. Product rendering and external delivery happen in Publish.

Version history

Reports keep a revision history. Use Version History from the report editor to inspect saved revisions and compare adjacent revisions. Revision diffs are for audit and troubleshooting; they do not currently provide rollback.

Filter

• Search: Items can be filtered by string search
• Display: Number of items displayed per page
• Offset: Number that defines first item displayed
• Filter: Filter time range (creation date)
• Completed/Incomplete: Filter by report status
• Report Type: Filter by Report Type

Screenshots

Incomplete reports created today

Add new report item

Deleting multiple reports at once

Report item view

5 - Publish

Functionalities

Publish manages Products. A Product combines one or more Reports with a Product Type, renders the result into a file format, and sends the rendered file to a configured Publisher.

Product setup

1. Select a Product Type.
2. Add supported Report Items.
3. Save the Product.
4. Render the Product.
5. Preview or download the rendered output.
6. Publish manually, or enable autopublish with a default Publisher.

Product Types define the renderer, template, output format, and which Report Types are compatible. See Product Types.

Render and preview

Rendering is a worker-backed action. HTML, JSON, text, and PDF Products can be previewed in the Product view after rendering. Other formats can be downloaded after rendering.

If workers are down, the render job can still be queued but will not complete until a worker starts. See Background Jobs.

Publishing

Manual publishing sends the rendered Product to a selected Publisher. Autopublish requires a default Publisher; when enabled, Taranis AI can automatically render and publish matching Products during report/product workflows.

Supported Publishers and their parameters are documented in Publishers.

Filter

• Search: Items can be filtered by string search
• Items per page: Number of items displayed per page
• Filter: Show items created today, this week, or this month

Screenshot

6 - Dashboard

The Dashboard displays frequent topics, application statistics, and shortcuts into common analyst queues. Topic cards open Assess with the matching tag filter. Statistic fields link to the related sections.

Saved Assess filters can also appear as Dashboard cards. Use them for recurring queues such as unread important Stories, language-specific monitoring, or shift handover views.

Conflict resolution

experimental feature

Conflicts can currently be resolved in the Connectors section accessible in the general and administration dashboard.

In the Conflict Resolution View it is possible to resolve given conflicts.

In the view, all stories that have conflicts will be shown in expandable cards. One by one it is possible to inspect them and resolve them.

There are two main conflict types:

• Story conflicts
• News Item conflicts

Story conflicts

Story conflicts occur when change of the same story happened in MISP and locally as well. In that case a clean update cannot happen.

This example shows that in the Story in MISP was a News Item removed and two other Story fields (comments and description) were updated.

News Item Conflicts

The News Item conflicts occur when stories have divergent news items and cannot be automatically updated due to a local change. The user is offered to choose from 2 options of resolution:

1. Keep Local Stories + Add Unique Items - local Stories stay untouched and News Items that are new are ingested separately.
2. Take Incoming Story (Replace Local) - local Stories are ungrouped and the incoming Story is ingested as is.

Conflicts are stored in a temporary memory, to encourage a fresh MISP Collector recollection, before resolving conflicts and to prevent conflict resolution with outdated data.

7 - User settings

User details

Username and user’s organization are displayed.

Change user settings

• Split view: Show Assess and story details side by side.
• Compact view: Use condensed spacing for tables and lists.
• Show charts: Display dashboard visualizations when available.
• Dark theme: Follows system or browser settings.
• Infinite scroll: Automatically load more results near the bottom of a list.
• Advanced story edit options: Expose extra Story Edit actions such as AI assisted summary, title, and sentiment actions.
• Language: Switch interface language. Currently only English is available; a German translation is currently experimental.
• Timezone: Choose how local times are displayed, or use the browser timezone.
• End of shift: Used by Assess filtering and workflow planning.
• Live updates: Enable Server-Sent Events so the UI can react to changes without a manual refresh.

Onboarding tours

Completed onboarding tours are tracked per user. They can be reset from user settings so they are shown again.

Password

Database-auth users can change their password from user settings. Keep passwords unique and do not reuse credentials from other systems.

Keyboard shortcuts

The settings page lists the available keyboard shortcuts. They are currently static and cannot be customized per user. Common Assess shortcuts include adding selected Stories to a report and bookmarking selected Stories.

8 - Administration

Screenshots

Administration dashboard showing statistics and all its functionalities (sidebar)

8.1 - User Management

Organizations

Organizations can be added with following parameters defining them: name, description, address.

Roles

Define roles with permissions. Roles are then assigned to users to control access to administration, Assess, Analyze, Publish, connector, and worker features.

Users

Manage users and assign them roles and an organization.

The user table supports JSON import and export:

• Export downloads users_export.json. If users are selected, only those users are exported; otherwise all users are exported.
• The export format is version: 1 with a data list containing user names and usernames.
• Passwords are never exported.
• Import accepts the exported JSON format, then assigns the selected organization and selected roles to every imported user.
• Existing usernames are skipped and reported in a warning instead of failing the whole import.
• Imported users without a password stay passwordless. Use this for externally authenticated users, or set a local password afterwards.

Operational CLI

Operators can repair existing database-auth users from inside the core container with taranis-cli.

Reset an existing user’s password:

docker exec -it core taranis-cli set-password admin
kubectl exec -it deploy/core -- taranis-cli set-password admin

For non-interactive automation, pass the password through standard input:

printf '%s\n' 'new-password' | docker exec -i core taranis-cli set-password admin --password-stdin

Replace an existing user’s complete role list:

docker exec -it core taranis-cli set-roles user Admin
kubectl exec -it deploy/core -- taranis-cli set-roles user Admin User

set-roles accepts exact role names or role IDs. It replaces the full role list; include every role the user should keep. Prefer the password prompt or --password-stdin so passwords do not land in shell history.

Screenshots

Add new Organization

Edit basic user role

Add new User

8.2 - OSINT workflow

Functionalities

1. Create OSINT Sources
2. Add word lists
3. Adapt word list’s functionality
4. Enable include/exclude list filtering
5. Bot selection
6. Collect Sources

1. Create OSINT Sources

• Import/Export: Sources can be imported and exported as JSON
• CRUD: Sources can be created, updated and deleted. For each source a collector, feed URL and the content location can be defined among other things.

2. Add word lists

• Import/Export: Word lists can be imported and exported as json
• CRUD: Word lists can be created, updated and deleted.

3. Adapt word list’s functionality

Word lists can have the following functionalities (displayed under “usage”):

• Collector Includelist: Collected news items using words of this word list will be accepted
• Collector Excludelist: Collected news items using words of this word list will not be accepted
• Tagging Bot: Collected news items will be tagged with words from these word lists
• Collector Includelist & Tagging Bot: A word list can be used for tagging and include listing

4. Enable include/exclude list filtering

To activate include or exclude lists, they need to be added to the default source group.

It has to be mentioned, that this include/exclude filtering happens during the news item collection. Therefore, only filtered news items will be stored in the database and displayed in “Assess”.

5. Bot selection

After the collection, it is possible to adapt news items.

Common bots include:

• Wordlist Bot: Tags News Items by wordlist.
• IOC Bot: Finds indicators of compromise in News Items.
• NLP Bot: Tags News Items via named entity recognition.
• Story Clustering Bot: Groups related Stories.
• Summary Bot: Summarizes Stories and can generate Story titles.
• Sentiment Analysis Bot: Adds sentiment attributes to News Items.
• Cybersecurity Classifier Bot: Classifies whether content is cybersecurity related.

CRUD: Bots can be created, updated and deleted.

Index: Decides the order of bots

RUN_AFTER_COLLECTOR: Indicates if bot is active after collection

LLM-backed bots can use the optional LLM Bot Service. Full bot configuration is documented in Bots.

6. Collect Sources

After all settings are made, sources can be collected. Either collect all sources by clicking on the “collect sources” button, or collect single sources.

8.3 - OSINT Sources

Functionalities

OSINT Sources define where collectors gather data from. Administrators can:

• Create and edit sources.
• Enable or disable scheduled collection.
• Assign a source rank and icon.
• Preview collector output before ingesting it into Assess.
• Import and export source configuration as JSON.
• Collect one source or all sources on demand.

Create a new source

1. Select New Item to open editor at the bottom.
2. Enter a Name and, optionally, a Description.
3. Select a collector. See Collectors.
4. Configure collector parameters.
5. Save the source.

Use Source Rank to prioritize or classify sources for analyst workflows. Upload an icon when source identity should be visible on Story and News Item cards.

Preview a source

Use Preview from the source editor or table actions to run the collector without storing the result in Assess. Preview results are shown as Story cards. If a preview fails, use Retrigger preview after adjusting the source configuration.

Preview is especially useful for RSS, Simple Web, and RT sources where XPath, headers, proxies, or content extraction settings may need tuning.

Enable and disable sources

The source state button controls whether the source is active for scheduled collection. Disabling a source unschedules its Redis/RQ cron job; enabling it schedules the source again when it has a refresh interval.

Import sources

Select Import and choose the source JSON file. Imports support current exports and legacy source JSON formats.

Export sources

Select Export to download a JSON file. If sources are selected, only those sources are exported; otherwise all visible sources are exported.

Collect from sources

Use Collect to collect one source, or Collect All to collect all enabled sources. Collection is worker-backed; if the job is queued but does not run, verify worker health in Background Jobs.

8.4 - Report Types

Attributes

Desired attributes need to be created first. Then they can be managed by the admin user. Besides name, description and default value also type, validator and validator parameter can be set.

Report Types - CRUD

• Create: Report types can be created (“New item”). After adding a new attribute group, different attributes can be added to this group.
• Read & Update: Report types (including their attribute groups) can be updated by clicking on them in the list. Their update will not affect Reports, which already use the Report Type
• Delete: One or multiple reports can be deleted at once.

Screenshots

Add new Attribute

Report Types - Create new Report Type

Report Types - Add new Attribute Group

Report Types - Select new Attribute from list

8.5 - Bots

Bots run as worker jobs. They can be triggered manually, scheduled with REFRESH_INTERVAL, or run after collection when RUN_AFTER_COLLECTOR is enabled.

Available bots

Implementation details are available in the worker bot source.

Common settings

Scheduled bots are handled by Redis/RQ. See Background Jobs for worker and scheduler health checks.

LLM-backed bots

The optional LLM Bot Service can serve several bot endpoints.

Per-bot endpoint fields take precedence over worker environment defaults. After upgrading from older standalone bot services, update LLM-backed bot parameters that still point to summary_bot, nlp_bot, story_bot, or sentiment_analysis_bot. If you keep the Cybersecurity Classifier Bot, make sure its configured classifier endpoint is still deployed.

The Summary Bot only updates Story titles when TITLE_ENDPOINT is configured and the Story contains more than one News Item.

Sentiment output

The Sentiment Analysis Bot writes these News Item attributes:

• sentiment_score
• sentiment_category

The Story Edit advanced view displays the sentiment status when these attributes are present.

8.6 - Collectors

Supported options

1. RSS Collector
2. Simple Web Collector
3. RT Collector
4. MISP Collector

The administration view now allows users to use the Preview feature to see the result of the configuration without the items being processed further for the Assess view. This feature is available for RSS, Simple Web and RT collector.

RSS Collector

RSS Collector enables Taranis AI to collect data from a user-defined RSS feed (See RSS feeds details).

• Required fields:
  • FEED_URL
• Optional fields:
  • USER_AGENT
  • PROXY_SERVER
  • USE_GLOBAL_PROXY (ignore anything set in the PROXY_SERVER field, use what is currently set as a default in Settings; learn more in section Settings)
  • ADDITIONAL_HEADERS [accepts a valid json] (can be used to add additional headers, not all headers work as expected)
  • CONTENT_LOCATION (selects which field from the RSS entry should be used as the item content, for example description or content:encoded; when the collector uses content from the RSS entry, it first checks the field named here; if that field is empty or missing, it falls back through content, content:encoded, summary, and description)
  • USE_FEED_CONTENT (controls whether the collector uses content from the RSS entry itself or fetches the linked article page; if this is enabled, the collector uses RSS entry content; if it is disabled, the collector fetches the linked article page; if it is not set, a non-empty CONTENT_LOCATION effectively enables using RSS entry content)
  • XPATH (optional XPath expression used to limit the extracted content to a specific element; if USE_FEED_CONTENT is enabled, XPath is applied to the HTML content taken from the RSS entry; if the XPath does not match, the collector keeps the original RSS entry content; if USE_FEED_CONTENT is disabled, XPath is applied to the fetched article page; if the XPath does not match there, the collector does not fall back to another extraction method and the content may be empty)
  • TLP_LEVEL
  • REFRESH_INTERVAL (see Bots - refresh_interval)
  • DIGEST_SPLITTING On/Off (creates News Items out of URLs present in the Summary field of RSS feed)
  • DIGEST_SPLITTING_LIMIT (default: 30)
  • BROWSER_MODE On/Off (see Browser Mode)

Basic configuration

• Example:
  • FEED_URL: https://www.bmi.gv.at/rss/bmi_presse.xml

Advanced configuration

The RSS Collector supports the use of XPath for locating elements. (See Simple Web Collector Advanced configuration)

• Example:
  • FEED_URL: https://www.bmi.gv.at/rss/bmi_presse.xml
  • XPATH: //*[@id=“getting-started-web-console-creating-new-project_openshift-web-console”]
  • ADDITIONAL_HEADERS: { "AUTHORIZATION": "Bearer Token1234", "X-API-KEY": "12345", "Cookie": "firstcookie=1234; second-cookie=4321", }

Simple Web Collector

Simple Web Collector enables Taranis AI to collect data using web URLs and XPaths.

• Required field:
  • WEB_URL
• Optional fields:
  • USER_AGENT
  • PROXY_SERVER
  • USE_GLOBAL_PROXY
  • ADDITIONAL_HEADERS
  • XPATH (set to specify the location of the scraped element on the website)
  • TLP_LEVEL
  • DIGEST_SPLITTING On/Off
  • DIGEST_SPLITTING_LIMIT (default: 30)
  • BROWSER_MODE On/Off (see Browser Mode)

Basic configuration

The simplest way to use this collector is to use the WEB_URL field only. By using only the WEB_URL field, Taranis-AI autonomously determines the content to be collected. Even though it is mostly reliable, sometimes it is not perfect.

Advanced configuration

When content cannot be reliably collected using the Basic configuration, adding the attribute XPATH (See tutorial how to find it), can be useful. It is crucial to specify the XPath of the precise element containing the desired data.

Configuration for Mastodon Feeds

To set up an RSS Collector for collecting posts from a Mastodon hashtag or user, follow these steps:

1. Finding the Mastodon RSS Feed URL:

   • Hashtag Feed: Add .rss to the hashtag URL. For example, to collect posts tagged with #cybersecurity: https://mastodon.social/tags/cybersecurity.rss
   • User Feed: Similarly, add .rss to the user’s profile URL. Example: https://mastodon.social/@username.rss

2. Creating a New RSS Source with Required Parameters: When creating the new RSS source, configure it with the following parameters. Here’s an example of how to fill out the fields:

   • FEED_URL: Enter the RSS feed URL for the Mastodon hashtag or user (e.g., https://mastodon.social/tags/cybersecurity.rss).
   • CONTENT_LOCATION Set this to "summary" to specify the main content location within each RSS entry.
   • REFRESH_INTERVAL Set the refresh interval in crontab-like style, see Bots - refresh_interval.
   • DIGEST_SPLITTING is set to "false" since we’re not splitting entries into multiple items.

Configuration for Darkweb Feeds

Extend your compose.yml with a tor service, e.g.

tor:
  image: "docker.io/dperson/torproxy:latest"
  deploy:
    restart_policy:
      condition: always
  environment:
    # LOCATION: "AT"
  logging:
    driver: "json-file"
    options:
      max-size: "200k"
      max-file: "10"

Read details about the used docker image here

The important setting is “PROXY_SERVER” in the OSINT Source you want to crawl.

RT Collector

RT Collector enables Taranis AI to collect data from a user-defined Request Tracker instance.

RT Collector collects tickets, translates all ticket attachments into individual News Items. A ticket is represented via a Story. It also collects ticket Custom Fields and saves it as key-value pairs represented with Story attributes, visible whilst Story editing. On each collector execution an update to existing Stories occurs, so editing the Story values in Taranis AI is not recommended and handling it more like read-only items is better.

• Required fields:

  • BASE_URL: Base URL of the RT instance (e.g. http://localhost).
  • RT_TOKEN: User token for the RT instance.

• Optional fields:

  • SEARCH_QUERY: query to use for filtering tickets (e.g. owner=‘user1’). It is possible to check this manually by: http://<rt_address>/REST/2.0/tickets?query=owner=‘user1’
  • FIELDS_TO_INCLUDE: case-sensitive, comma-separated values; example: Email, IP; if not set, all ticket custom fields are ingested
  • ADDITIONAL_HEADERS
  • TLP_LEVEL
  • USER_AGENT
  • PROXY_SERVER
  • USE_GLOBAL_PROXY

MISP Collector

Until the definitions of our MISP Objects are not officially part of the MISP platform, feel free to import them manually (see MISP Objects). This allows to edit the information of News Items and Story data directly in the MISP instance without Taranis AI.

MISP Collector enables Taranis AI to collect MISP events.

• Required fields:

  • URL: Base URL to the MISP instance (e.g. https://localhost)
  • API_KEY: API key to access the instance (see MISP Automation API)

• Optional fields:

  • SSL_CHECK: if enabled, the SSL certificate will be validated
  • SHARING_GROUP_ID: set to the ID of a sharing group, if only one sharing group should be collected (see Create and manage Sharing Groups).
  • REQUEST_TIMEOUT
  • USER_AGENT
  • PROXY_SERVER
  • USE_GLOBAL_PROXY
  • ADDITIONAL_HEADERS
  • REFRESH_INTERVAL

How MISP Collector works

Essentially it works exactly like other collectors with one exception: conflicts. Given the nature of the collaborative environment of MISP events (they can be changed in the MISP platform by the owning organisation and secondary organisations can submit change requests using the MISP proposals). Due to that, there will likely occur conflicts when attempting to update existing Stories that were, in the meantime, internally modified.

Generally, conflicts occur the moment, a Story is modified internally, and has not been pushed to MISP immediately. Therefore, it is recommended to always try to keep Stories in sync with the MISP events. To update them in MISP with the Story (see Connectors).

Digest Splitting

Digest Splitting is a feature that allows the user to split all available URLs in the located element into individual News Items. The Digest Splitting Limit is the maximum number of URLs that will be split into individual News Items. If the limit is reached, the remaining URLs are dropped. The Digest Splitting Limit is set to 30 News Items by default but can be adjusted by the administrator. Useful in case of timeouts during collection of too many News Items.

Browser Mode

Collectors will fail if the web page content is only available with JavaScript. In that case it is possible to turn on the Browser Mode. All requests will have JavaScript enabled, therefore, it is slower and can use more resources.

8.7 - Connectors

Supported options:

• MISP Connector
  • Usage of the MISP Connector

MISP Connector

The MISP connector is currently in an experimental stage. Please submit issues when you discover any problems or need support with its usage.

Until the definitions of our MISP Objects are not officially part of the MISP platform, feel free to import them manually (see MISP Objects). This enables you to edit the objects of News Items and Story data directly in you MISP instances without Taranis AI.

MISP Connector enables Taranis AI to push Stories to MISP in the representation of MISP Events.

The created events contain automatically an Event Report based on the Story content (currently it encompasses the Story description and Story summary, if you feel the Event Report would benefit extending with more information, please open a feature request for it here).

First the user with administrative privileges needs to make sure, the permissions connected to Connectors usage are assigned appropriately, by default, they are not assigned to any user, not even the admins themselves. Then the Connector needs to be setup in the Admin section under the Connectors tab.

Explanation of individual permissions:

• Connector user access - ability to share a story to a Connector
• Config connector access - ability to access admin Connector configuration
• Config connector create - ability to create a Connector
• Config connector delete - ability to delete a Connector
• Config connector update - ability to update a Connector configuration

• Required parameters:

  • URL: Base URL to the MISP instance (e.g. https://localhost)
  • API_KEY: API key to access the instance (see MISP Automation API)
  • ORGANISATION_ID: ID of your organisation, usually starts with ID=1 (It is very important that this value is correct, otherwise the tool will not work properly!)

• Optional parameters:

  • SSL_CHECK: if enabled, the SSL certificate will be validated
  • SHARING_GROUP_ID: set to the ID of a sharing group, if you want to collect only one sharing group (see Create and manage Sharing Groups)
  • DISTRIBUTION: Integer value of the distribution of the created events (see Setting distribution and Creating an event)
  • REQUEST_TIMEOUT
  • USER_AGENT
  • PROXY_SERVER
  • ADDITIONAL_HEADERS
  • REFRESH_INTERVAL

  Usage of the MISP Connector

  To send a story to MISP, use the button “Share to Connector” in Story options in Assess. When an update to the Story is later on made, it is recommended to share the change immediately, you need to do this manually like the first time.

  Before a Story is pushed repeatedly to update the MISP event, it is important to check if any proposals are pending in the MISP event, as it would override the original content of it and would make it difficult to resolve the proposals correctly.

  

  When a Story is collected, that is not owned by your configured organisation, it is possible to update it in Taranis AI and by using the same “Share to Connector” button in the Story options a proposal to the event is created. Then the owning organisation should review this proposal, and approve or reject the changes.

8.8 - Publishers

Supported options

Publishers send rendered Products to external systems.

Keep API keys, passwords, app secrets, and private keys in protected configuration. Do not reuse personal credentials for shared publishers.

Email Publisher

The Email Publisher allows sending out Products.

• Fields:
  • SMTP_SERVER_ADDRESS*: Address of the SMTP server.
  • SMTP_SERVER_PORT*: Port of the SMTP server.
  • SERVER_TLS: Enable/Disable TLS.
  • EMAIL_USERNAME: Login username for the SMTP server.
  • EMAIL_PASSWORD: Login password for the SMTP server.
  • EMAIL_SENDER*: Sender of the email for message envelope.
  • EMAIL_RECIPIENT*: Email address of the recipient for message envelope. It is possible to use only one email recipient.
  • EMAIL_SUBJECT: Subject of the email.

Note: The EMAIL_SENDER and EMAIL_RECIPIENT parameters are used to construct the message envelope used by the transport agents. Message headers are not modified by these parameters in any way.

Required fields are marked with a *.

General usage

Once the publisher is created, it becomes available in the “Publish” section of each product. To send out a product via email, the product must be “Rendered” first. To render a product, use the option available in the product’s view.

Kafka Publisher

The Kafka Publisher sends each rendered Product as a JSON message to the configured topic.

• Message key: the generated product file name.
• Message body: object_name, mime_type, and data.
• KAFKA_SECURITY_PROTOCOL defaults to PLAINTEXT.
• Supported security protocols are PLAINTEXT and SASL_PLAINTEXT.
• When KAFKA_SECURITY_PROTOCOL is SASL_PLAINTEXT, set KAFKA_SASL_MECHANISM, KAFKA_SASL_USERNAME, and KAFKA_SASL_PASSWORD.
• KAFKA_ACKS defaults to all.
• KAFKA_RETRIES defaults to 3.
• KAFKA_SEND_TIMEOUT defaults to 30 seconds.

TAXII Publisher

The TAXII Publisher pushes STIX bundle objects to a TAXII 2.1 collection. The rendered Product must be valid JSON with type: bundle and a non-empty objects list.

Set AUTH_TYPE to basic with USERNAME and PASSWORD, or to bearer with API_TOKEN. Configure either TAXII_API_ROOT_URL directly or TAXII_DISCOVERY_URL so Taranis AI can discover the API root.

S3 Publisher

The S3 Publisher uploads the rendered Product to S3-compatible object storage. If the configured bucket does not exist, Taranis AI creates it before uploading.

8.9 - Product Types

Prebuilt Product Types

• CERT Daily Report
• Default HTML Presenter
• Default MISP Presenter
• Default PDF Presenter
• Default TEXT Presenter

Editing Product Types

All crucial fields are editable, with the most important being Type, Template, and Report Types.

• Type: It’s the responsibility of the administrator to ensure the selected type is compatible with the subsequently provided template.
• Template: Users can select from prebuilt templates or add new ones.
• Report Types: This field determines which types of reports can be added to the products.

Template paths are validated before use. A Product Type cannot render a Report Type unless that Report Type is associated with the Product Type.

Create new Product Types

While there are several prebuilt product types available, users also have the option to create their own product types using custom templates.

It can be beneficial to create custom Product Types to meet desired results with the publishers.

Example of creating a simple new template using Jinja2

This is an example to render arbitrary values and loop over attributes.

1. Create a new file with a unique name in src/core/core/static/presenter_templates.
2. Write a custom template:

   TITLE: {{ data.report_items[0].get('title') | default('No title provided', true) }}<br>
   DATE CREATED: {{ data.report_items[0].get('created') | default('Not available', true) }}<br>
   LAST UPDATED: {{ data.report_items[0].get('last_updated') | default('Not available', true) }}<br>
   {% for name, attribute in data.report_items[0].get('attributes').items() %}
   {{ name }}: {{ attribute }}<br>
   {% endfor %}
   

3. Select the new template in the Product Type.
4. Render a test Product before using the Product Type in production.

Advanced behaviour

If needed, templates can be utilized for more complex renderings by leveraging custom attributes.

Currently, this functionality is demonstrated in the text_template.txt file, where the attribute omission of type “Omit Keys” allows for the exclusion of unnecessary attributes from publication. To employ this feature, the administrator simply needs to add this attribute to the relevant report type. Then, within a specific report (Analyze View), they can specify the attributes to omit by listing them as comma-separated strings.

It is essential to ensure that the “Name” used for the report type attribute matches exactly with the key used in the template.

8.10 - Settings

Options

1. Default TLP Level
2. Default Collector Proxy
3. Default Collector Interval

Default TLP Level

Learn more about what TLP version 2.0 is under first.org/tlp/.

Default value: Clear

Options: Green, Amber, Amber+Strict, Red

All newly collected items by Collectors use this default TLP value. When this setting is changed, it does not affect the items that are already present in Assess section.

This setting can be overridden for each collector with the TLP_LEVEL field.

Default Collector Proxy

When a default collector proxy is set, it can then be used in the collectors by enabling the switch USE_GLOBAL_PROXY.

The following matrix of the states applies

• 🟢 Per-source proxy set: A proxy is set or not for a collector.
• 🔵 Default proxy set: A default proxy is set or not in global settings.
• USE_GLOBAL_PROXY: In the collector (OSINT Source) settings, the switch USE_GLOBAL_PROXY is enabled.
• Result: The resulting state.

Default Collector Interval

This value is used for REFRESH_INTERVAL for all collectors (OSINT Sources) when this field is left unset individually for all collectors. The syntax is the same as REFRESH_INTERVAL in bot settings.

Export options

• Export all Stories: Export all stories without any metadata (tags, etc.).
• Export all Stories with metadata: Export all stories with all the metadata (tags, attributes, likes, dislikes, relevance, etc.). It is not safe to use these data back for importing (some tags and attributes are used for internal purposes and could create unexpected behaviour). Drop metadata before importing, if doing so.

Danger Zone

• Clear all Worker Queues: Delete all messages from all worker queues. This action cannot be undone.
• Delete all Tags: Delete all tags from all Stories in the system. This action cannot be undone.

See Background Jobs before clearing worker queues.

8.11 - OpenAPI

Description

The admin user can access the Taranis API through Swagger UI. Swagger UI displays OpenAPI specifications as an interactive API documentation. Current OpenAPI specifications are available at https://github.com/taranis-ai/taranis-ai/blob/master/src/core/core/static/openapi3_1.yaml

Functionalities 👤

see: Swagger UI

Screenshots

Taranis instance is alive

9 - User Stories

9.1 - User Stories [Admin]

Configure Sources

As an admin, I need to configure OSINT sources to be gathered for intelligence gathering purposes.

Word Lists

As an admin, I need the ability to utilize Word Lists for filtering news items during collection or enhancing them with a Bot. This includes the capability to import and export word lists and apply them based on their designated usage, such as adding tags with the word_list_bot.

Configure Report Types

As an admin, I need the ability to configure new report types.

Configure Users

As an admin, I need to manage user accounts by creating and deleting users, ensuring they have the necessary access for their tasks.

Configure ACLs and roles

As an admin, I need to configure Access Control Lists (ACLs) and roles to define permissions for each role. This allows me to effectively manage user permissions, control access to sensitive information, and maintain compliance with organizational policies and regulations.

9.2 - User Stories [Analyst]

Topics Dashboard [Dashboard]

As an analyst, I require access to a Topics Dashboard feature that displays the most important news topics. This dashboard should prioritize the most frequently occurring tags, offering a snapshot of the prevailing themes and subjects within the collected news items.

Assess Stories [Assess]

As an analsyt, I want to review all stories gathered in a fixed time period. I want to be able to set a stard and end date for items to be displayed. If I set these time limits I want to display Stories with pageing otherwise there will be an infintescroll representing the everchanging nature of stories.

Search, Filter and Sort [Assess]

As an analyst, I need the capability to search for news items by entering any text string. To provide a ranked list of results based on the relevance to the search query, enabling me to quickly and effectively identify the most pertinent articles for further analysis.

Vote on Story [Assess]

As an analyst, I want to mark news items as important by voting on them. To allow me to quickly identify and categorize significant articles for easy retrieval at a later time. Each Story includes buttons for down and up voting as well as for marking an story as important. Via a shortcut (ctrl+i) I can mark all selected stories as important.

Mark as read [Assess]

As an analyst, I want to mark news items as read to prevent myself and other anlyst from viewing the same story multiple times. Each Story contains a button to mark a story as read or unread if already marked as read. The same behaviour can be toggled via a shortcut (ctrl+space).

Tags [Assess]

As an analyst, I need the ability to filter news items based on tags, attributes, or important keywords. To allow me to quickly find relevant news items by applying a tag filter within the tool. The interface should provide an option to enter or select tags, and display the filtered results. In scenarios where no news items match the selected tags, it should result in an empty story list.

Create and edit News Item [Assess]

As an analyst, I need a feature that enables me to create news items, specifying details such as title, publish date, review, link, article content, and attributes. To maintain data integrity, the editing function will be disabled for any news item once it is included in a report. For ease of use, each news item has an edit button in the Asses view.

Manage Report [Analyze]

As an analyst, I want to create and edit reports directly within the Analyse view. I can create reports from predefined list of report types managed by an administrator. I can edit the metadata of this report, and add Stories to it. I can mark the report as “completed” to allow further processing and publishing.

Manage Product [Publish]

As an analyst, I require a feature to create reports directly within the Analyse view. I can create reports from predefined list of report types managed by an administrator. I can edit the metadata of this report, and add Stories to it. I can mark the report as “completed” to allow further processing and publishing.

Publish Product [Publish]

As an analyst, I want to publish the findings of a report. So they can be viewed outside of Taranis AI. I can choose only Reports that match my Product type. I can render a preview of the Product before sharing. I can choose the destination where to publish from a predefined list (publishers) managed by an administrator.

9.2.1 - Workflow [Analyst]

Upon logging in, the analyst is greeted by the Dashboard, which displays significant tags, statistics, and saved Assess filter shortcuts. This view sets the context for the analyst’s tasks ahead.

To enhance workflow efficiency, please review the available hotkeys. Additionally, for simplified filtering, set the “End of Shift” time in the user settings. This feature allows the system to display only articles published since the last end of shift, ensuring you see content that hasn’t been reviewed yet.

Assess

To assess your items, go to the Assess section and set the time filter. Apply the “not read” and “not important” filters. Save this as a default filter if it is your normal review queue. Mark as read any items that have been read but are considered unimportant. Continue working through these items until all are marked as read, focusing only on checking summaries.

Next, set the filter to “not read” and “important”. Verify the importance of each item and mark it as read if not important. Check whether the item is part of an older report and determine if it still adds value. If not, remove the “important” tag and mark the item as read. If multiple items discuss the same topic, merge them.

Use Omnisearch for quick jumps, for example story: tag:ransomware read:false, report: weekly, or product: stix.

To update a summary manually or with AI, first click the “Edit Story” button. Then, edit the summary yourself or use the AI actions when advanced story edit options are enabled. Send important or sector-specific items via a connector or add them to the relevant reports. Optionally, vote Stories up or down and bookmark Stories that need follow-up.

Finally, remove the “important” tag and mark the item as read. For greater efficiency, consider using the time filter to focus on the most recent content.

Additional tasks during assess

During the review process in the Assess tab, the analyst has several tools at their disposal to optimize their workflow:

Voting on Stories: The analyst can vote stories up or down and mark them as important using buttons or the shortcut (Ctrl+I). This helps highlight stories of particular relevance.

Mark as Read: To maintain efficiency and avoid redundancy, the analyst can mark stories as read or unread using a button or the shortcut (Ctrl+Space).

Tags: Tag filters can be applied to narrow down the selection to the most relevant articles, improving focus. If a story needs editing or creation, the analyst can do so directly within the Assess tab, where news items can be adjusted until they are locked into a report. This ensures the content remains fresh and accurate.

Bookmarks: Bookmark collections are private per user. Use them for follow-up queues, handover topics, and Stories that should stay visible after they are marked read.

Version history: Story version history can be used to inspect how a Story changed over time, especially after manual edits, grouping, ungrouping, bot updates, or connector synchronization.

Once all relevant stories are collected and reviewed, the analyst moves to the Analyze tab to finalize the report and mark it as completed. This step transitions the process from review to dissemination

Analyze

To analyze your items, go to the Analyze section and review the Report. Add Stories to the appropriate sections, save changes, inspect version history when needed, and mark the Report as completed when it is ready for publication.

Publish

Finally, the Publish tab is where the compiled Report becomes a Product ready for external consumption. The analyst chooses a Product Type, renders and reviews the final Product preview, then publishes manually or uses autopublish with a default Publisher.

10 - Contribution Guidelines

See https://github.com/taranis-ai/.github/blob/master/CONTRIBUTING.md