# Security Twitter CLI

A Docker Compose application that provides a Python-based CLI tool for security researchers to monitor Twitter for vulnerability data, threat intelligence, and security-related discussions.

## Features

- **Hashtag Search**: Monitor security-related hashtags like #cybersecurity, #malware, #vulnerability
- **Trending Analysis**: Get security-related trending topics
- **Vulnerability Detection**: Automatic CVE pattern detection and extraction
- **Security Scoring**: Intelligent relevance scoring for tweets
- **Multiple Formats**: Output in table, JSON, or CSV format
- **Caching**: Redis-based caching to manage API rate limits
- **Logging**: Comprehensive logging for monitoring and analysis

## Quick Start

1. **Get Twitter API Credentials**
   - Apply for a Twitter Developer account at https://developer.twitter.com/
   - Create a new app and generate API keys

2. **Configure Environment**
   ```bash
   cp .env.example .env
   # Edit .env with your Twitter API credentials
   ```

3. **Build and Run**
   ```bash
   docker-compose up --build
   ```

4. **Search for Security Data**
   ```bash
   # Search for cybersecurity and malware tweets
   docker-compose run twitter-cli python main.py search -h cybersecurity -h malware

   # Get trending security topics
   docker-compose run twitter-cli python main.py trending

   # Analyze vulnerability mentions
   docker-compose run twitter-cli python main.py analyze -h vulnerability -h cve
   ```

## CLI Commands

### Search Command
```bash
python main.py search [OPTIONS]
```
- `-h, --hashtags`: Security hashtags to search (required, can use multiple)
- `-n, --max-results`: Maximum tweets per hashtag (default: 100)
- `-o, --output`: Output format: table/json/csv (default: table)
- `-s, --min-score`: Minimum security score threshold (default: 1.0)

### Trending Command
```bash
python main.py trending [OPTIONS]
```
- `-a, --analyze`: Show detailed analysis

### Analyze Command
```bash
python main.py analyze [OPTIONS]
```
- `-h, --hashtags`: Hashtags to analyze (required)
- `-n, --max-results`: Maximum tweets to analyze (default: 100)

## Example Usage

```bash
# Search for high-priority security alerts
docker-compose run twitter-cli python main.py search -h cybersecurity -h breach -s 3.0

# Export vulnerability data as JSON
docker-compose run twitter-cli python main.py search -h cve -h vulnerability -o json > vulns.json

# Monitor multiple security topics
docker-compose run twitter-cli python main.py search -h malware -h ransomware -h phishing -n 50
```

## Security Focus

This tool is designed specifically for **defensive security research**:
- Vulnerability disclosure monitoring
- Threat intelligence gathering
- CVE tracking and analysis
- Security trend identification
- Incident response support

## Data Storage

- Logs: `./data/security_twitter.log`
- Cache: Redis container with persistent volume
- Config: `./config/` directory (mounted volume)

## Requirements

- Docker and Docker Compose
- Twitter Developer Account with API access
- Internet connection for API calls

⚠️ **Twitter API Limitation**: The Twitter Free tier API only allows pulling 100 posts per month. Consider upgrading to a paid tier for production use or extensive monitoring.