osint-public-records-pkg 0.1.1
OSINT tool for public records (CAC Nigeria, OpenSanctions, Wikipedia).
License: MIT
Requires Python: >=3.8

# OSINT Public Records Package

A powerful, asynchronous Open Source Intelligence (OSINT) tool designed to retrieve public records from difficult-to-access sources. This package specializes in Nigerian Corporate Registry (CAC) data, Global Sanctions/PEP lists, and general encyclopedic data.

## Features

| Module | Source | Description |
|:---|:---|:---|
| **CAC Records** | **CAC Nigeria** | Access hidden ICRP & BOR endpoints to find registered companies, directors, and Persons with Significant Control (PSC). |
| **Sanctions Check** | **OpenSanctions** | Screen individuals against global sanctions lists, PEP (Politically Exposed Persons) lists, and criminal databases. |
| **Wiki Intel** | **Wikipedia** | Extract summaries, images, references, and related links for quick entity profiling. |

## Installation

### From Source
Navigate to the root directory of the package and install via pip:

```bash
cd OSINT-PUBLIC-RECORDS-PKG
pip install osint-public-records-pkg
```

### Dependencies
httpx (for asynchronous API requests)

beautifulsoup4 (for HTML parsing)

lxml (for fast XML/HTML processing)

requests (for synchronous operations)

### Configuration
To use the OpenSanctions module, you need an API Key. You can configure this in two ways:

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


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

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

###Method 2: Direct Initialization
Pass the key directly when initializing the class in Python.
```bash
sanctions = OpenSanctionsAPI(api_key="your_api_key_here")
```

### Usage Examples
1. Searching CAC Nigeria (Corporate Affairs Commission)
Find companies and retrieve Person with Significant Control (PSC) details using hidden API endpoints.

```bash
import asyncio
from osint_public_records_pkg import CACRecordsAPI

async def search_cac():
    cac = CACRecordsAPI()
    
    # Step 1: Search for a company name
    print("--- Searching ICRP ---")
    company_name = "Dangote Cement"
    results = await cac.search_name(company_name)
    
    if results["success"]:
        top_match = results["records"][0]
        print(f"Found: {top_match['name']} (RC: {top_match['rc_number']})")
        
        # Step 2: Get Directors/PSC details (BOR)
        # Note: This searches the Beneficial Ownership Register
        print("\n--- Fetching PSC Details ---")
        psc_data = await cac.get_company_psc_details(
            company_name=top_match['name'], 
            rc_number=top_match['rc_number']
        )
        
        if psc_data["success"]:
            for person in psc_data["psc_records"]:
                print(f"Director/Owner: {person['name']}")
                print(f"Address: {person['address']}")
                print(f"Nationality: {person['nationality']}\n")

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

```

2. Screening for Sanctions & PEPs
Check if an individual appears on international sanctions lists (OFAC, UN, EU) or is a Politically Exposed Person.

``` bash
import asyncio
from osint_public_records_pkg import OpenSanctionsAPI

async def check_sanctions():
    # Ensure you have set OPEN_SANCTIONS_API_KEY in your env
    api = OpenSanctionsAPI()
    
    target = "Vladimir Putin"
    print(f"--- Screening {target} ---")
    
    result = await api.search_entity(target)
    
    if result["success"]:
        record = result["records"][0]
        print(f"Name: {record['name']}")
        print(f"Is PEP: {record['is_pep']}")
        print(f"Is Sanctioned: {record['is_sanctioned']}")
        print(f"Reason: {record.get('designation_reason', 'N/A')}")
        print(f"Countries: {record['country']}")
    else:
        print("No records found or API error.")

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

```

3. General Intelligence (Wikipedia)
Quickly gather background information, images, and references.

``` bash
from osint_public_records_pkg import WikipediaScraper

def get_wiki_info():
    wiki = WikipediaScraper()
    query = "Central Bank of Nigeria"
    
    print(f"--- Wiki Lookup: {query} ---")
    data = wiki.search(query)
    
    if "error" not in data:
        print(f"Title: {data['title']}")
        print(f"Summary: {data['summary'][:200]}...") # First 200 chars
        
        print("\nSections:")
        for section in data['sections'][:3]:
            print(f"- {section}")
            
        print("\nReferences Found:", len(data['references']))

get_wiki_info()

```

### Disclaimer
This tool is intended for legitimate Open Source Intelligence (OSINT) research, compliance checking, and investigative journalism.

CAC Data: Accesses public endpoints (icrp.cac.gov.ng and bor.cac.gov.ng). While these are public, automated scraping should be done responsibly and in accordance with local regulations.

OpenSanctions: Usage is subject to the OpenSanctions API Terms of Service.