osint-security-threat-pkg 0.1.0
OSINT tool for security threats and global firepower.
Requires Python: >=3.8

# OSINT Security Threat Package

A specialized Open Source Intelligence (OSINT) tool designed for cybersecurity threat intelligence and geopolitical military capability analysis. This package combines the power of the AlienVault Open Threat Exchange (OTX) API with an automated Global Firepower index scraper.

## Features

| Module | Source | Description |
|:---|:---|:---|
| **OTX Scanner** | **AlienVault OTX** | Asynchronous wrapper for the OTX API. Fetches pulse counts, malware analyses, and threat intelligence for domains, IPs, and file hashes. |
| **Firepower Scraper** | **Global Firepower** | Selenium-based automated scraper that extracts structured military statistics, financial metrics, manpower, and logistics data for any country. |

## Prerequisites

* **Python 3.8+**
* **Google Chrome:** Required for the `GlobalFirePowerScraper` (Selenium manages the ChromeDriver automatically via `webdriver-manager`).
* **AlienVault API Key:** Required for the `OtxScanner`.

## Installation

Navigate to the root directory of the package and install it via pip:

```bash
cd OSINT-SECURITY-THREAT-PKG
pip install osint-security-threat-pkg
```
This will automatically install necessary dependencies including selenium, beautifulsoup4, and the official OTXv2 Python SDK.

### Configuration
To use the OTX Scanner, you must provide an AlienVault OTX API key. You can get a free key by signing up at otx.alienvault.com.

Method 1: Environment Variable (Recommended)
Set the variable in your terminal or .env file. The package will automatically detect it.

Linux / macOS:
```bash
export ALIENTVAULT_OTX_API_KEY="your_api_key_here"
```

Windows (PowerShell):
```PowerShell
$env:ALIENTVAULT_OTX_API_KEY="your_api_key_here"
```

Method 2: Direct Initialization
Pass the key directly when initializing the class in Python.

```Python
from osint_security_threat_pkg import OtxScanner

scanner = OtxScanner(api_key="your_api_key_here")
```


### Usage Examples
1. Threat Intelligence (AlienVault OTX)
Scan a domain asynchronously to check for associated malicious pulses and threat data.
```Python
import asyncio
from osint_security_threat_pkg import OtxScanner

async def check_threats():
    # Will use ALIENTVAULT_OTX_API_KEY from environment if not passed
    scanner = OtxScanner()
    domain = "pastebin.com"
    
    print(f"--- Scanning Domain: {domain} ---")
    result = await scanner.scan(domain)
    
    if result["success"]:
        data = result["data"]
        general_info = data.get("general", {})
        pulse_info = general_info.get("pulse_info", {})
        
        print(f"Total Pulses (Threat Reports): {pulse_info.get('count', 0)}")
        
        # Print the first few related pulses
        for pulse in pulse_info.get("pulses", [])[:3]:
            print(f"- {pulse.get('name')} (Tags: {', '.join(pulse.get('tags', []))})")
    else:
        print(f"Error: {result.get('error')}")

if __name__ == "__main__":
    asyncio.run(check_threats())

```

2. Geopolitical Military Data (Global Firepower)
Scrape comprehensive military strength data for a specific country. Using the with statement (context manager) ensures the headless browser closes automatically when finished. 

```python
from osint_security_threat_pkg import GlobalFirePowerScraper

def check_military_strength():
    country = "nigeria"
    print(f"--- Fetching Military Data for: {country.upper()} ---")
    
    # Initialize the scraper (headless=True runs the browser invisibly)
    with GlobalFirePowerScraper(headless=True) as scraper:
        # Search and optionally save the raw JSON output to a file
        data = scraper.search(country, save_to_file=False)
        
        if data:
            overview = data.get('overview', {}).get('ranks', {})
            print(f"Global Firepower Rank: {overview.get('GFP Rank', 'N/A')}")
            
            manpower = data.get('manpower', {}).get('statistics', {})
            if 'Available Manpower' in manpower:
                print(f"Available Manpower: {manpower['Available Manpower'].get('value')}")
            
            financials = data.get('financials', {}).get('statistics', {})
            if 'Defense Budget' in financials:
                print(f"Defense Budget: {financials['Defense Budget'].get('value')}")
        else:
            print("Failed to retrieve data.")

if __name__ == "__main__":
    check_military_strength()
```    

### Disclaimer
This tool is intended for educational purposes and legitimate Open Source Intelligence (OSINT) research.

The OtxScanner usage is subject to the AlienVault OTX Terms of Service.

The GlobalFirePowerScraper automates interactions with a public website. Users are responsible for adhering to the site's robots.txt and avoiding excessive request rates that could degrade the service.