What Is the Garbage Collection Manager in OpenCTI and How to Configure It

The garbage collection manager in OpenCTI is a background cron-driven process that permanently erases soft-deleted entities from the trash after a configurable retention period, processing records in batches to avoid database contention.

The garbage collection manager ensures that deleted entities in OpenCTI do not accumulate indefinitely in your database. When users delete objects through the interface, OpenCTI creates DeleteOperation records that hold the data in a trash state. The manager runs continuously to purge these records once they exceed the retention threshold, freeing storage and maintaining compliance with data retention policies.

What the Garbage Collection Manager Does

The manager executes as a lock-protected background task registered via registerManager(GARBAGE_COLLECTION_MANAGER_DEFINITION) in src/manager/garbageCollectionManager.ts. Its core responsibilities include:

• Scheduled Execution: Runs at fixed intervals (default every 60,000 milliseconds) to query for expired delete operations.
• Batch Processing: Fetches up to BATCH_SIZE records (default 10,000) per execution cycle to prevent memory exhaustion.
• Permanent Deletion: Invokes confirmDelete from src/modules/deleteOperation/deleteOperation-domain.ts to physically remove data older than DELETED_RETENTION_DAYS (default 7 days).
• Fault Isolation: Logs errors for individual deletion failures without halting the entire batch operation.

The manager only activates when both the global trash feature and the manager itself are enabled, as defined by the condition enabledByConfig: TRASH_ENABLED && GARBAGE_COLLECTION_MANAGER_ENABLED in the source.

Architecture and Source Code Locations

Manager Registration and Handler

The garbage collection manager integrates into OpenCTI's platform architecture through several key files:

• src/manager/garbageCollectionManager.ts: Contains the garbageCollectionHandler function and the GARBAGE_COLLECTION_MANAGER_DEFINITION object that specifies the cron schedule, lock key, and enablement conditions.
• src/manager/index.ts: Loads the garbage collection module, ensuring it becomes part of the platform's ManagerModule registry during startup.
• src/utils/access: Provides the execution context identifier (garbage_collection_manager) used for permission checks during deletion operations.

Domain Logic and Data Flow

The actual deletion workflow relies on the delete operation domain layer:

1. findOldDeleteOperations (in src/modules/deleteOperation/deleteOperation-domain.ts): Queries the database for DeleteOperation records where the deletion timestamp exceeds DELETED_RETENTION_DAYS.
2. confirmDelete: Permanently removes the entity data and associated relationships from the database.
3. Redis Locking: The manager uses a distributed lock (lock_key) to prevent concurrent execution across clustered OpenCTI instances.

Configuring the Garbage Collection Manager

All configuration parameters reside under the garbage_collection_manager key in the platform configuration hierarchy.

Default Configuration Values

The baseline settings are defined in config/default.json:

"garbage_collection_manager": {
  "enabled": true,
  "lock_key": "garbage_collection_manager_lock",
  "batch_size": 10000,
  "interval": 60000,
  "deleted_retention_days": 7
}

Environment Variable Overrides

You can override defaults using environment variables prefixed with GARBAGE_COLLECTION_MANAGER__:

export GARBAGE_COLLECTION_MANAGER__ENABLED=false
export GARBAGE_COLLECTION_MANAGER__INTERVAL=300000
export GARBAGE_COLLECTION_MANAGER__DELETED_RETENTION_DAYS=30
export GARBAGE_COLLECTION_MANAGER__BATCH_SIZE=5000

YAML Configuration Example

For Docker Compose or Kubernetes deployments, specify settings in your config.yml or environment block:

garbage_collection_manager:
  enabled: true
  interval: 120000        # Run every 2 minutes

  batch_size: 2000        # Process 2,000 items per batch

  deleted_retention_days: 14
  lock_key: "garbage_collection_manager_lock"

Note that setting app:trash:enabled to false globally disables the garbage collection manager regardless of its specific configuration, as the manager depends on the trash feature being active.

Manual Execution for Debugging

You can trigger the garbage collection process manually during development or troubleshooting by invoking the handler directly:

import { garbageCollectionHandler } from './src/manager/garbageCollectionManager';

(async () => {
  console.log('Starting manual garbage collection...');
  await garbageCollectionHandler();
  console.log('Garbage collection completed.');
})();

This bypasses the cron scheduler and Redis locking mechanisms, so use it only in single-instance development environments.

Summary

• The garbage collection manager automatically purges soft-deleted entities from OpenCTI's trash after the retention period expires.
• Configuration occurs via config/default.json, environment variables with the GARBAGE_COLLECTION_MANAGER__ prefix, or YAML files.
• Default settings retain deleted items for 7 days, processing 10,000 records per minute.
• The manager requires both the global trash feature (app:trash:enabled) and its own enabled flag to run.
• Source code is located primarily in src/manager/garbageCollectionManager.ts and src/modules/deleteOperation/deleteOperation-domain.ts.

Frequently Asked Questions

How often does the garbage collection manager run in OpenCTI?

By default, the manager executes every 60,000 milliseconds (1 minute). You can adjust this interval by setting the interval configuration parameter (in milliseconds) via environment variables or YAML configuration. The manager uses a Redis lock to ensure only one instance runs the cleanup job in clustered deployments.

What happens if I disable the garbage collection manager?

When disabled, OpenCTI retains all DeleteOperation records indefinitely in the trash, causing your database to grow continuously. Soft-deleted entities remain recoverable but consume storage space. Disabling the manager does not affect the ability to manually restore items from trash during the retention period, but it prevents automatic permanent deletion.

How do I extend the trash retention period beyond the default 7 days?

Set the deleted_retention_days parameter to your desired value. For example, export GARBAGE_COLLECTION_MANAGER__DELETED_RETENTION_DAYS=30 to retain deleted items for 30 days before permanent erasure. Changes take effect on the next scheduled run; previously expired records will be purged if they exceed the new threshold.

Where can I find the complete configuration reference for the garbage collection manager?

The official configuration documentation resides in docs/docs/deployment/configuration.md (lines 425-429), which lists all available parameters including enabled, lock_key, batch_size, interval, and deleted_retention_days. The implementation details and default values are defined in src/manager/garbageCollectionManager.ts and config/default.json within the opencti-graphql package.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}