Bulk Tag Deletion Script v2

CSV-driven bulk tag deletion with intelligent tenant management for Plextrac instances.

Overview

This script allows you to bulk delete tags from Plextrac objects using a CSV file input. It supports multiple object types and includes intelligent tenant-level tag cleanup to ensure complete tag removal across your platform.

Features

• CSV Input: Process hundreds of tags from a single CSV file
• Multiple Object Types: Supports clients, assets, reports, findings, and writeups
• Intelligent Tenant Management: Automatically cleans up tenant-level tags when appropriate
• Dry Run Mode: Preview changes before executing
• Error Recovery: Generates recovery files for failed operations
• CTEM Ready: Prepared for future CTEM instance support

Requirements

• Python 3+
• pip
• pipenv

Installation

git clone <this_repo>
cd path/to/cloned/repo
pipenv install

Setup

Configuration File

In the config.yaml file, add your Plextrac instance URL and credentials:

instance_url: https://yourapp.plextrac.com
username: your_username
password: your_password

The script supports automatic authentication and re-authentication every 15 minutes. If MFA is enabled, you'll be prompted for the code during re-authentication.

CSV File Format

Create a CSV file with a single column of tags to delete. No header row - each row should contain one tag value.

Example tags.csv:

old_tag_1
deprecated_tag
temp_tag_2023
test_environment

Usage

Basic Usage

pipenv run python main.py --csv-file tags.csv --objects all

Advanced Usage

# Delete tags from specific object types only
pipenv run python main.py --csv-file tags.csv --objects clients,assets

# Skip tenant-level cleanup for faster execution
pipenv run python main.py --csv-file tags.csv --objects all --ignore-tenant-cleanup

# Preview changes without executing (Dry Run)
pipenv run python main.py --csv-file tags.csv --objects all --dry-run

Command Line Arguments

Argument	Required	Description
--csv-file	Yes	Path to CSV file containing tags to delete (single column, no headers)
--objects	Yes	Object types: all or comma-separated list: clients,assets,reports,findings,writeups
--ignore-tenant-cleanup	No	Skip tenant-level tag cleanup for faster execution
--dry-run	No	Preview changes without making actual modifications
--instance-url	No	Plextrac instance URL (e.g., https://yourapp.plextrac.com). CLI arg takes precedence over config.yaml
--username	No	Username for authentication. CLI arg takes precedence over config.yaml
--password	No	Password for authentication. CLI arg takes precedence over config.yaml

Object Types

Supported Objects

• clients: Client records and their associated tags
• assets: Individual assets with their tags
• reports: Report objects with their tags
• findings: Individual findings within reports
• writeups: Writeup database entries
• ctem_instances: CTEM instances

Tenant Tag Management

The script includes intelligent tenant-level tag cleanup:

When --objects all:

• Automatically removes tenant tags after successful object cleanup
• Assumes complete tag removal across all object types

When --objects specific:

• Checks all other object types for remaining tag instances
• Only removes tenant tags if no instances exist anywhere in the platform
• Ensures no orphaned tenant tags remain

When --ignore-tenant-cleanup:

• Skips all tenant-level operations for maximum speed
• Use when you only need partial tag removal

Error Handling and Recovery

Comprehensive Logging

• Detailed progress tracking with iteration metrics
• Object-level error logging with specific failure reasons
• Complete operation summary with success/failure statistics

Recovery Files

If any operations fail, the script generates a timestamped recovery file:

failed_tags_20240211_143022.csv

This file contains tags that failed to be deleted, allowing you to retry only the failed operations.

Error Categories

1. Data Loading Errors: Failed to retrieve objects from the API
2. Update Errors: Failed to update specific objects
3. Tenant Cleanup Errors: Failed to remove tenant-level tags

Script Execution Flow

1. Parse CLI Arguments: Validate parameters and load configuration
2. Load Tags from CSV: Read and validate tag list
3. Authenticate: Connect to Plextrac instance
4. Load Objects: Retrieve target objects using improved data utilities
5. Process Deletions: Remove tags from specified object types
6. Tenant Cleanup: Intelligent tenant-level tag management
7. Generate Reports: Create recovery files and operation summary
8. Display Results: Comprehensive completion statistics

Examples

Example 1: Complete Tag Cleanup

pipenv run python main.py --csv-file deprecated_tags.csv --objects all

• Removes specified tags from all object types
• Cleans up tenant-level tags automatically
• Generates recovery file if needed

Example 2: Partial Cleanup with Dry Run

pipenv run python main.py --csv-file test_tags.csv --objects clients,reports --dry-run

• Shows what would be deleted from clients and reports
• No actual changes made
• Useful for verification before production runs

Example 3: Fast Specific Cleanup

pipenv run python main.py --csv-file temp_tags.csv --objects assets --ignore-tenant-cleanup

• Removes tags only from assets
• Skips tenant cleanup for maximum speed
• Useful when you know tags aren't used elsewhere

Example 4: CLI Authentication Arguments

# All authentication via CLI arguments
pipenv run python main.py --csv-file tags.csv --objects all --instance-url "https://myinstance.plextrac.com" --username "admin" --password "secret123"

# Mix CLI auth with config.yaml
pipenv run python main.py --csv-file tags.csv --objects clients,assets --username "admin"

# All from config.yaml (fallback behavior)
pipenv run python main.py --csv-file tags.csv --objects all

• CLI authentication arguments take precedence over config.yaml
• Useful for automation and scripts where config.yaml isn't desired
• If not provided via CLI, falls back to config.yaml values

Troubleshooting

Common Issues

1. CSV Format Errors: Ensure single column, no headers
2. Authentication Failures: Check URL and credentials in config.yaml
3. Permission Errors: Verify user has tag modification permissions
4. Network Timeouts: Script includes automatic retry logic

Log Analysis

Check the generated log file for:

• [EXCEPTION] entries for detailed error information
• Progress metrics for performance monitoring
• Success/failure statistics for operation analysis

Recovery Process

If operations fail:

1. Check the generated failed_tags_*.csv file
2. Review log file for specific error details
3. Fix underlying issues (permissions, network, etc.)
4. Re-run script with recovery file as input