# CatSCAN v2.0 🐾
**Terraform Cloud multi-workspace scanner with retro vibes**
CatSCAN is a secure, high-performance CLI tool that uses the Terraform Cloud API to scan all workspaces in your organization and display a comprehensive summary of resources. Built for platform and DevOps engineers who want secure, high-performance visibility across all Terraform workspaces.
CatSCAN uses the [Terraform Cloud API v2](https://developer.hashicorp.com/terraform/cloud-docs/api-docs) for authentication, workspace queries, and state analysis.
Follow the launch post on LinkedIn for discussion and feature requests.
---
## Features
### Core Functionality
* **Comprehensive Scanning** - Fetches all workspaces from Terraform Cloud with pagination support
* **Deep State Analysis** - Downloads and parses state files (JSON/ZIP) with nested module support
* **Resource Discovery** - Counts and categorizes all resource types across workspaces
* **Parallel Processing** - Multi-threaded scanning with configurable worker pools
* **Connection Pooling** - Efficient HTTP session management for faster API calls
### Security & Authentication
* **Keyring Integration** - Secure credential storage using system keyring (encrypted)
* **Multiple Auth Methods** - Environment variables, keyring, or interactive input
* **Input Validation** - Sanitization of organization names and API tokens
* **Credential Management** - Built-in UI for updating/deleting stored tokens
### User Interface
* **Retro ASCII Art** - Old-school terminal aesthetics for the modern DevOps warrior
* **Rich Terminal UI** - Beautiful tables and panels powered by Rich library
* **Cross-Platform** - Native support for Windows, macOS, and Linux
* **Curses Mode** - Buttery-smooth navigation on Linux terminals
### Data & History
* **Historical Tracking** - Maintains scan history with detailed resource breakdowns
* **Interactive History Browser** - Navigate past scans with arrow keys
* **Persistent Storage** - Scan results saved in JSON format
* **Detailed Views** - Drill down into specific scans and workspace resources
---
## 📦 Installation
### From GitHub (Recommended for v2.0)
```bash
git clone https://github.com/cloudsifar/catscan-2.0.git
cd catscan-2.0
pip install -e .
```
### From PyPI
```bash
pip install catscan-terra
```
---
## 🎮 Usage
### Basic Commands
```bash
# Run CatSCAN with default settings
catscan
# Enable debug logging
catscan --debug
# Custom log file
catscan --log-file /path/to/catscan.log
# Skip the ASCII banner (for automation)
catscan --no-banner
```
### Authentication Methods
#### Method 1: Secure Keyring Storage (Recommended)
On first run, CatSCAN will prompt for your credentials and offer to store them securely:
```
🔒 Secure Configuration Setup
✅ Keyring available - credentials will be stored securely
Your token will be encrypted in the system credential store
Organization name: my-terraform-org
Terraform Cloud API Token: **********************
💾 Save token securely to system keyring? (Y/n): y
```
#### Method 2: Environment Variables
For CI/CD pipelines or automation:
```bash
export TFC_ORG_NAME="my-terraform-org"
export TFC_TOKEN="your-api-token-here"
catscan
```
**Security Tips for Environment Variables:**
- Never commit `.env` files to version control
- Use CI/CD secret management features
- On Linux/Mac: Add to `~/.bashrc` or `~/.zshrc` with restricted permissions
- On Windows: Use User Environment Variables (not System)
- Consider using tools like `direnv` or `dotenv` for project-specific variables
#### Method 3: Interactive Input
Simply run `catscan` without any configuration, and it will guide you through setup.
---
## 🎯 Menu Navigation
### Main Scan Results Menu
After completing a scan, you'll see:
```
╭────────────────────────────────────────────────────────────────╮
│ What would you like to do? │
│ │
│ ╭─────────────────────────────╮ │
│ │ [D] View detailed results │ ← See all resources by type │
│ │ [H] View scan history │ ← Browse previous scans │
│ │ [R] Run another scan │ ← Refresh data │
│ │ [S] Security settings │ ← Manage stored credentials │
│ │ [P] Platform info (debug) │ ← Troubleshooting info │
│ │ [Q] Quit │ │
│ ╰─────────────────────────────╯ │
╰────────────────────────────────────────────────────────────────╯
```
### History Browser Controls
- **↑/↓** - Navigate through scan history
- **Enter** - View detailed scan results
- **Escape** - Return to main menu
- **Page Up/Down** - Jump through pages (Linux/curses mode)
### Credential Manager
Access via `[S] Security settings`:
- View all organizations with stored tokens
- Verify token validity
- Update expired tokens
- Delete stored credentials
---
## 📊 Example Output
### Scan Summary
```
Found 42 workspaces
📊 Deployed Resources by Workspace (acme-corp)
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Workspace ┃ Resources ┃ Status ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ prod-app │ aws_instance(12), aws_db_instance(3), aws_security_group(8) │ ✅ 23 │
│ staging │ aws_s3_bucket(5), aws_lambda_function(8) │ ✅ 13 │
│ dev-a │ aws_instance(5), aws_cloudwatch_log_group(2), aws_iam_role(3) │ ✅ 10 │
│ dev-b │ aws_lambda_function(6), aws_iam_policy(2), aws_sqs_queue(2) │ ✅ 10 │
│ data-pipeline │ aws_glue_job(4), aws_glue_catalog_table(2), aws_s3_bucket(2) │ ✅ 8 │
│ billing-analytics │ aws_athena_database(1), aws_athena_table(2), aws_s3_bucket(2) │ ✅ 5 │
│ security-hub │ aws_guardduty_detector(1), aws_securityhub_standards_subscription(2)│ ✅ 3 │
│ dev-c │ aws_instance(4), aws_ecr_repository(3), aws_codebuild_project(2) │ ✅ 9 │
│ qa-env │ aws_instance(3), aws_rds_cluster(2), aws_elasticache_cluster(1) │ ✅ 6 │
│ prod-infra │ aws_nat_gateway(2), aws_route_table(3), aws_vpc(1) │ ✅ 6 │
│ devops │ aws_codepipeline(2), aws_codebuild_project(2), aws_iam_role(2) │ ✅ 6 │
│ ml-models │ aws_sagemaker_model(3), aws_s3_bucket(2), aws_lambda_function(2) │ ✅ 7 │
│ iot-core │ aws_iot_thing(5), aws_lambda_function(3), aws_dynamodb_table(2) │ ✅ 10 │
│ user-auth │ aws_cognito_user_pool(2), aws_lambda_function(2), aws_iam_role(1) │ ✅ 5 │
│ prod-db │ aws_rds_cluster(3), aws_db_subnet_group(1), aws_kms_key(1) │ ✅ 5 │
│ legacy-archive │ aws_s3_bucket(2), aws_glacier_vault(2) │ ✅ 4 │
│ sandbox │ No state │ 🚫 No State │
│ testing │ No state │ 🚫 No State │
│ temp-experiment │ No state │ 🚫 No State │
│ prototype-1 │ No state │ 🚫 No State │
└────────────────────┴─────────────────────────────────────────────────────────────────────┴──────────────┘
✅ Scan Complete!
Successfully processed: 37 workspaces
Empty/Error workspaces: 5
Total resources discovered: 159
✓ Including nested modules
```
### Detailed Resource View
```
All Resources by Type and Workspace (acme-corp)
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓
┃ Workspace ┃ Resource Type ┃ Count ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩
│ prod-app │ aws_instance │ 12 │
│ │ aws_db_instance │ 3 │
│ │ aws_security_group │ 8 │
│ │ aws_iam_role │ 2 │
│ │ aws_cloudwatch_log_group │ 1 │
│ │ aws_elb │ 1 │
│ │ aws_launch_template │ 2 │
│ │ aws_autoscaling_group │ 1 │
│ │ aws_kms_key │ 1 │
│ │ aws_route53_record │ 3 │
│ │ aws_acm_certificate │ 2 │
│ │ aws_s3_bucket │ 2 │
│ │ aws_secretsmanager_secret │ 1 │
│ ─────────────────────────────────────────────────────── │
│ staging │ aws_s3_bucket │ 5 │
│ │ aws_lambda_function │ 8 │
│ │ aws_iam_policy │ 2 │
│ │ aws_api_gateway_rest_api │ 1 │
│ │ aws_cloudwatch_alarm │ 3 │
│ │ aws_dynamodb_table │ 1 │
│ │ aws_sns_topic │ 1 │
│ │ aws_ssm_parameter │ 2 │
└────────────────────┴────────────────────────────┴───────┘
```
---
## 🔧 Logging and Debugging
### Debug Mode
Enable comprehensive logging to troubleshoot issues:
```bash
# Logs to default location: ./catscan_YYYYMMDD_HHMMSS.log
catscan --debug
# Custom log location
catscan --log-file /var/log/catscan.log --debug
```
### Log Levels
The debug log includes:
- API request/response details
- Authentication flow
- Token verification steps
- Workspace processing progress
- Rate limiting information
- Error stack traces
### Common Issues
1. **Keyring not available**: Install with `pip install keyring`
2. **Curses UI issues**: Set `CATSCAN_NO_CURSES=true` to disable
3. **Rate limiting**: CatSCAN automatically handles Terraform Cloud rate limits
4. **SSL errors**: Check your system certificates or corporate proxy settings
---
## 🏗️ Architecture
CatSCAN v2.0 features a fully modular architecture:
```
catscan/
├── auth/ # Authentication & credential management
├── api/ # Terraform Cloud API client
├── scanner/ # Core scanning logic
├── storage/ # Data persistence
├── ui/ # Terminal user interface
└── utils/ # Cross-platform utilities
```
---
## 🤝 Contributing
I welcome suggestions and improvements! If you're new to GitHub or pull requests don't worry – here's the usual workflow:
1. **Fork the repository** on GitHub to your own account.
2. **Clone your fork** locally:
```bash
git clone https://github.com/<your-username>/catscan-2.0.git
cd catscan-2.0
```
3. **Create a feature branch**:
```bash
git checkout -b feature/my-feature
```
4. **Make your changes**, then **commit** them:
```bash
git add .
git commit -m "Describe your change here"
```
5. **Push** the branch to your fork:
```bash
git push origin feature/my-feature
```
6. **Open a Pull Request** against `cloudsifar/catscan-2.0` via GitHub's UI.
* You'll automatically be notified of comments, CI results, and merge status.
* I review and manually merge when ready.
Feel free to open **issues** first if you want to discuss big changes or report bugs.
---
## 👨💻 Author
**Simon Farrell** – Creator of CatSCAN and Terraform enthusiast.
Follow me on [LinkedIn](https://www.linkedin.com/in/simon-farrell-cloud/) for updates.
---
## 📜 License
This project is licensed under the [MIT License](https://opensource.org/license/mit).
---
## 🎸 Why CatSCAN?
Because every DevOps team needs a tool that makes infrastructure scanning feel less like work and more like playing with a retro terminal from the 80s. I was inspired because I wanted something like a cat command in bash, which scanned my workspaces and displayed it in the terminal. Plus I like cats.
```
/\_ _/\
( o.o ) Meow! Found 42 workspaces to scan...
)==Y==(
/ \
( | || | )
\__\_/\_/__/
```
Raw data
{
"_id": null,
"home_page": null,
"name": "catscan-terra",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "terraform, terraform-cloud, infrastructure, scanner, devops, cloud",
"author": null,
"author_email": "Simon Farrell <simon81farrell@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/8e/cf/4f7ae592660f6adf2aacbf267b4992383ad15c32d7418488dd2013da2c3d/catscan_terra-2.0.0.tar.gz",
"platform": null,
"description": "# CatSCAN v2.0 \ud83d\udc3e\r\n\r\n**Terraform Cloud multi-workspace scanner with retro vibes**\r\n\r\nCatSCAN is a secure, high-performance CLI tool that uses the Terraform Cloud API to scan all workspaces in your organization and display a comprehensive summary of resources. Built for platform and DevOps engineers who want secure, high-performance visibility across all Terraform workspaces.\r\n\r\nCatSCAN uses the [Terraform Cloud API v2](https://developer.hashicorp.com/terraform/cloud-docs/api-docs) for authentication, workspace queries, and state analysis.\r\n\r\nFollow the launch post on LinkedIn for discussion and feature requests.\r\n\r\n---\r\n\r\n## Features\r\n\r\n### Core Functionality\r\n* **Comprehensive Scanning** - Fetches all workspaces from Terraform Cloud with pagination support\r\n* **Deep State Analysis** - Downloads and parses state files (JSON/ZIP) with nested module support\r\n* **Resource Discovery** - Counts and categorizes all resource types across workspaces\r\n* **Parallel Processing** - Multi-threaded scanning with configurable worker pools\r\n* **Connection Pooling** - Efficient HTTP session management for faster API calls\r\n\r\n### Security & Authentication\r\n* **Keyring Integration** - Secure credential storage using system keyring (encrypted)\r\n* **Multiple Auth Methods** - Environment variables, keyring, or interactive input\r\n* **Input Validation** - Sanitization of organization names and API tokens\r\n* **Credential Management** - Built-in UI for updating/deleting stored tokens\r\n\r\n### User Interface\r\n* **Retro ASCII Art** - Old-school terminal aesthetics for the modern DevOps warrior\r\n* **Rich Terminal UI** - Beautiful tables and panels powered by Rich library\r\n* **Cross-Platform** - Native support for Windows, macOS, and Linux\r\n* **Curses Mode** - Buttery-smooth navigation on Linux terminals\r\n\r\n### Data & History\r\n* **Historical Tracking** - Maintains scan history with detailed resource breakdowns\r\n* **Interactive History Browser** - Navigate past scans with arrow keys\r\n* **Persistent Storage** - Scan results saved in JSON format\r\n* **Detailed Views** - Drill down into specific scans and workspace resources\r\n\r\n---\r\n\r\n## \ud83d\udce6 Installation\r\n\r\n### From GitHub (Recommended for v2.0)\r\n\r\n```bash\r\ngit clone https://github.com/cloudsifar/catscan-2.0.git\r\ncd catscan-2.0\r\npip install -e .\r\n```\r\n\r\n### From PyPI\r\n\r\n```bash\r\npip install catscan-terra\r\n```\r\n\r\n---\r\n\r\n## \ud83c\udfae Usage\r\n\r\n### Basic Commands\r\n\r\n```bash\r\n# Run CatSCAN with default settings\r\ncatscan\r\n\r\n# Enable debug logging\r\ncatscan --debug\r\n\r\n# Custom log file\r\ncatscan --log-file /path/to/catscan.log\r\n\r\n# Skip the ASCII banner (for automation)\r\ncatscan --no-banner\r\n```\r\n\r\n### Authentication Methods\r\n\r\n#### Method 1: Secure Keyring Storage (Recommended)\r\n\r\nOn first run, CatSCAN will prompt for your credentials and offer to store them securely:\r\n\r\n```\r\n\ud83d\udd12 Secure Configuration Setup\r\n \u2705 Keyring available - credentials will be stored securely\r\n Your token will be encrypted in the system credential store\r\n\r\nOrganization name: my-terraform-org\r\nTerraform Cloud API Token: **********************\r\n\ud83d\udcbe Save token securely to system keyring? (Y/n): y\r\n```\r\n\r\n#### Method 2: Environment Variables\r\n\r\nFor CI/CD pipelines or automation:\r\n\r\n```bash\r\nexport TFC_ORG_NAME=\"my-terraform-org\"\r\nexport TFC_TOKEN=\"your-api-token-here\"\r\ncatscan\r\n```\r\n\r\n**Security Tips for Environment Variables:**\r\n- Never commit `.env` files to version control\r\n- Use CI/CD secret management features\r\n- On Linux/Mac: Add to `~/.bashrc` or `~/.zshrc` with restricted permissions\r\n- On Windows: Use User Environment Variables (not System)\r\n- Consider using tools like `direnv` or `dotenv` for project-specific variables\r\n\r\n#### Method 3: Interactive Input\r\n\r\nSimply run `catscan` without any configuration, and it will guide you through setup.\r\n\r\n---\r\n\r\n## \ud83c\udfaf Menu Navigation\r\n\r\n### Main Scan Results Menu\r\n\r\nAfter completing a scan, you'll see:\r\n\r\n```\r\n\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\r\n\u2502 What would you like to do? \u2502\r\n\u2502 \u2502\r\n\u2502 \u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e \u2502\r\n\u2502 \u2502 [D] View detailed results \u2502 \u2190 See all resources by type \u2502\r\n\u2502 \u2502 [H] View scan history \u2502 \u2190 Browse previous scans \u2502\r\n\u2502 \u2502 [R] Run another scan \u2502 \u2190 Refresh data \u2502\r\n\u2502 \u2502 [S] Security settings \u2502 \u2190 Manage stored credentials \u2502\r\n\u2502 \u2502 [P] Platform info (debug) \u2502 \u2190 Troubleshooting info \u2502\r\n\u2502 \u2502 [Q] Quit \u2502 \u2502\r\n\u2502 \u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f \u2502\r\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\r\n```\r\n\r\n### History Browser Controls\r\n\r\n- **\u2191/\u2193** - Navigate through scan history\r\n- **Enter** - View detailed scan results\r\n- **Escape** - Return to main menu\r\n- **Page Up/Down** - Jump through pages (Linux/curses mode)\r\n\r\n### Credential Manager\r\n\r\nAccess via `[S] Security settings`:\r\n- View all organizations with stored tokens\r\n- Verify token validity\r\n- Update expired tokens\r\n- Delete stored credentials\r\n\r\n---\r\n\r\n## \ud83d\udcca Example Output\r\n\r\n### Scan Summary\r\n```\r\nFound 42 workspaces\r\n\r\n\ud83d\udcca Deployed Resources by Workspace (acme-corp)\r\n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\r\n\u2503 Workspace \u2503 Resources \u2503 Status \u2503\r\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\r\n\u2502 prod-app \u2502 aws_instance(12), aws_db_instance(3), aws_security_group(8) \u2502 \u2705 23 \u2502\r\n\u2502 staging \u2502 aws_s3_bucket(5), aws_lambda_function(8) \u2502 \u2705 13 \u2502\r\n\u2502 dev-a \u2502 aws_instance(5), aws_cloudwatch_log_group(2), aws_iam_role(3) \u2502 \u2705 10 \u2502\r\n\u2502 dev-b \u2502 aws_lambda_function(6), aws_iam_policy(2), aws_sqs_queue(2) \u2502 \u2705 10 \u2502\r\n\u2502 data-pipeline \u2502 aws_glue_job(4), aws_glue_catalog_table(2), aws_s3_bucket(2) \u2502 \u2705 8 \u2502\r\n\u2502 billing-analytics \u2502 aws_athena_database(1), aws_athena_table(2), aws_s3_bucket(2) \u2502 \u2705 5 \u2502\r\n\u2502 security-hub \u2502 aws_guardduty_detector(1), aws_securityhub_standards_subscription(2)\u2502 \u2705 3 \u2502\r\n\u2502 dev-c \u2502 aws_instance(4), aws_ecr_repository(3), aws_codebuild_project(2) \u2502 \u2705 9 \u2502\r\n\u2502 qa-env \u2502 aws_instance(3), aws_rds_cluster(2), aws_elasticache_cluster(1) \u2502 \u2705 6 \u2502\r\n\u2502 prod-infra \u2502 aws_nat_gateway(2), aws_route_table(3), aws_vpc(1) \u2502 \u2705 6 \u2502\r\n\u2502 devops \u2502 aws_codepipeline(2), aws_codebuild_project(2), aws_iam_role(2) \u2502 \u2705 6 \u2502\r\n\u2502 ml-models \u2502 aws_sagemaker_model(3), aws_s3_bucket(2), aws_lambda_function(2) \u2502 \u2705 7 \u2502\r\n\u2502 iot-core \u2502 aws_iot_thing(5), aws_lambda_function(3), aws_dynamodb_table(2) \u2502 \u2705 10 \u2502\r\n\u2502 user-auth \u2502 aws_cognito_user_pool(2), aws_lambda_function(2), aws_iam_role(1) \u2502 \u2705 5 \u2502\r\n\u2502 prod-db \u2502 aws_rds_cluster(3), aws_db_subnet_group(1), aws_kms_key(1) \u2502 \u2705 5 \u2502\r\n\u2502 legacy-archive \u2502 aws_s3_bucket(2), aws_glacier_vault(2) \u2502 \u2705 4 \u2502\r\n\u2502 sandbox \u2502 No state \u2502 \ud83d\udeab No State \u2502\r\n\u2502 testing \u2502 No state \u2502 \ud83d\udeab No State \u2502\r\n\u2502 temp-experiment \u2502 No state \u2502 \ud83d\udeab No State \u2502\r\n\u2502 prototype-1 \u2502 No state \u2502 \ud83d\udeab No State \u2502\r\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n\r\n\u2705 Scan Complete!\r\n Successfully processed: 37 workspaces \r\n Empty/Error workspaces: 5 \r\n Total resources discovered: 159 \r\n \u2713 Including nested modules\r\n\r\n```\r\n\r\n### Detailed Resource View\r\n```\r\nAll Resources by Type and Workspace (acme-corp)\r\n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\r\n\u2503 Workspace \u2503 Resource Type \u2503 Count \u2503\r\n\u2521\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2547\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2529\r\n\u2502 prod-app \u2502 aws_instance \u2502 12 \u2502\r\n\u2502 \u2502 aws_db_instance \u2502 3 \u2502\r\n\u2502 \u2502 aws_security_group \u2502 8 \u2502\r\n\u2502 \u2502 aws_iam_role \u2502 2 \u2502\r\n\u2502 \u2502 aws_cloudwatch_log_group \u2502 1 \u2502\r\n\u2502 \u2502 aws_elb \u2502 1 \u2502\r\n\u2502 \u2502 aws_launch_template \u2502 2 \u2502\r\n\u2502 \u2502 aws_autoscaling_group \u2502 1 \u2502\r\n\u2502 \u2502 aws_kms_key \u2502 1 \u2502\r\n\u2502 \u2502 aws_route53_record \u2502 3 \u2502\r\n\u2502 \u2502 aws_acm_certificate \u2502 2 \u2502\r\n\u2502 \u2502 aws_s3_bucket \u2502 2 \u2502\r\n\u2502 \u2502 aws_secretsmanager_secret \u2502 1 \u2502\r\n\u2502 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2502\r\n\u2502 staging \u2502 aws_s3_bucket \u2502 5 \u2502\r\n\u2502 \u2502 aws_lambda_function \u2502 8 \u2502\r\n\u2502 \u2502 aws_iam_policy \u2502 2 \u2502\r\n\u2502 \u2502 aws_api_gateway_rest_api \u2502 1 \u2502\r\n\u2502 \u2502 aws_cloudwatch_alarm \u2502 3 \u2502\r\n\u2502 \u2502 aws_dynamodb_table \u2502 1 \u2502\r\n\u2502 \u2502 aws_sns_topic \u2502 1 \u2502\r\n\u2502 \u2502 aws_ssm_parameter \u2502 2 \u2502\r\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n\r\n```\r\n\r\n---\r\n\r\n## \ud83d\udd27 Logging and Debugging\r\n\r\n### Debug Mode\r\n\r\nEnable comprehensive logging to troubleshoot issues:\r\n\r\n```bash\r\n# Logs to default location: ./catscan_YYYYMMDD_HHMMSS.log\r\ncatscan --debug\r\n\r\n# Custom log location\r\ncatscan --log-file /var/log/catscan.log --debug\r\n```\r\n\r\n### Log Levels\r\n\r\nThe debug log includes:\r\n- API request/response details\r\n- Authentication flow\r\n- Token verification steps\r\n- Workspace processing progress\r\n- Rate limiting information\r\n- Error stack traces\r\n\r\n### Common Issues\r\n\r\n1. **Keyring not available**: Install with `pip install keyring`\r\n2. **Curses UI issues**: Set `CATSCAN_NO_CURSES=true` to disable\r\n3. **Rate limiting**: CatSCAN automatically handles Terraform Cloud rate limits\r\n4. **SSL errors**: Check your system certificates or corporate proxy settings\r\n\r\n---\r\n\r\n## \ud83c\udfd7\ufe0f Architecture\r\n\r\nCatSCAN v2.0 features a fully modular architecture:\r\n\r\n```\r\ncatscan/\r\n\u251c\u2500\u2500 auth/ # Authentication & credential management\r\n\u251c\u2500\u2500 api/ # Terraform Cloud API client\r\n\u251c\u2500\u2500 scanner/ # Core scanning logic\r\n\u251c\u2500\u2500 storage/ # Data persistence\r\n\u251c\u2500\u2500 ui/ # Terminal user interface\r\n\u2514\u2500\u2500 utils/ # Cross-platform utilities\r\n```\r\n\r\n---\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nI welcome suggestions and improvements! If you're new to GitHub or pull requests don't worry \u2013 here's the usual workflow:\r\n\r\n1. **Fork the repository** on GitHub to your own account.\r\n2. **Clone your fork** locally:\r\n ```bash\r\n git clone https://github.com/<your-username>/catscan-2.0.git\r\n cd catscan-2.0\r\n ```\r\n3. **Create a feature branch**:\r\n ```bash\r\n git checkout -b feature/my-feature\r\n ```\r\n4. **Make your changes**, then **commit** them:\r\n ```bash\r\n git add .\r\n git commit -m \"Describe your change here\"\r\n ```\r\n5. **Push** the branch to your fork:\r\n ```bash\r\n git push origin feature/my-feature\r\n ```\r\n6. **Open a Pull Request** against `cloudsifar/catscan-2.0` via GitHub's UI.\r\n * You'll automatically be notified of comments, CI results, and merge status.\r\n * I review and manually merge when ready.\r\n\r\nFeel free to open **issues** first if you want to discuss big changes or report bugs.\r\n\r\n---\r\n\r\n## \ud83d\udc68\u200d\ud83d\udcbb Author\r\n\r\n**Simon Farrell** \u2013 Creator of CatSCAN and Terraform enthusiast. \r\n\r\nFollow me on [LinkedIn](https://www.linkedin.com/in/simon-farrell-cloud/) for updates.\r\n\r\n\r\n---\r\n\r\n## \ud83d\udcdc License\r\n\r\nThis project is licensed under the [MIT License](https://opensource.org/license/mit).\r\n\r\n---\r\n\r\n## \ud83c\udfb8 Why CatSCAN?\r\n\r\nBecause every DevOps team needs a tool that makes infrastructure scanning feel less like work and more like playing with a retro terminal from the 80s. I was inspired because I wanted something like a cat command in bash, which scanned my workspaces and displayed it in the terminal. Plus I like cats.\r\n\r\n```\r\n /\\_ _/\\ \r\n ( o.o ) Meow! Found 42 workspaces to scan...\r\n )==Y==( \r\n / \\ \r\n ( | || | ) \r\n \\__\\_/\\_/__/\r\n```\r\n",
"bugtrack_url": null,
"license": null,
"summary": "CatSCAN: Terraform Cloud multi-workspace scanner. Secure observability tool for your organization's workspaces.",
"version": "2.0.0",
"project_urls": {
"Bug Reports": "https://github.com/cloudsifar/catscan-2.0/issues",
"Homepage": "https://github.com/cloudsifar/catscan-2.0",
"Source": "https://github.com/cloudsifar/catscan-2.0"
},
"split_keywords": [
"terraform",
" terraform-cloud",
" infrastructure",
" scanner",
" devops",
" cloud"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ba672c68efbd12d099c64650843c85fdba45423798452f0d4536addc3d155aeb",
"md5": "84d26bc9f5b683e35b8328862fe31ca4",
"sha256": "8b1511887eae7595b1f322391fe5661ba65c468a8cede0e7e3e0c630cd0e745e"
},
"downloads": -1,
"filename": "catscan_terra-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "84d26bc9f5b683e35b8328862fe31ca4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 45227,
"upload_time": "2025-08-01T19:32:21",
"upload_time_iso_8601": "2025-08-01T19:32:21.791350Z",
"url": "https://files.pythonhosted.org/packages/ba/67/2c68efbd12d099c64650843c85fdba45423798452f0d4536addc3d155aeb/catscan_terra-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8ecf4f7ae592660f6adf2aacbf267b4992383ad15c32d7418488dd2013da2c3d",
"md5": "176ab9c8dba8e55675929a443d37edc0",
"sha256": "ba40772958dd8dc7fdcd60ef1d8698e7696650a80f954d8e1b117c4fe0872c91"
},
"downloads": -1,
"filename": "catscan_terra-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "176ab9c8dba8e55675929a443d37edc0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 40347,
"upload_time": "2025-08-01T19:32:22",
"upload_time_iso_8601": "2025-08-01T19:32:22.788393Z",
"url": "https://files.pythonhosted.org/packages/8e/cf/4f7ae592660f6adf2aacbf267b4992383ad15c32d7418488dd2013da2c3d/catscan_terra-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 19:32:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cloudsifar",
"github_project": "catscan-2.0",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.28.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.0.0"
]
]
},
{
"name": "keyring",
"specs": [
[
">=",
"23.0.0"
]
]
}
],
"lcname": "catscan-terra"
}
JSON
