Metadata-Version: 2.1
Name: phishingdetectionapi
Version: 1.0.0
Summary: Python client for the PhishingDetectionAPI.com real-time phishing domain detection service
Home-page: https://www.phishingdetectionapi.com
Author: Alpha Quantum
Author-email: info@alpha-quantum.com
License: UNKNOWN
Description: # phishingdetectionapi
        
        A production-ready Python client for the [phishing detection API](https://www.phishingdetectionapi.com) — a continuously updated threat-intelligence service that maintains a database of 390,000+ DNS-verified active phishing domains. The package wraps the REST API in a clean, dependency-light interface so security engineers, SOC analysts, email-gateway developers, and compliance teams can query, filter, and synchronize phishing intelligence directly from Python.
        
        Phishing remains the single most common initial-access vector in cybersecurity breaches. According to industry reports, more than 80% of reported security incidents start with a phishing email or a malicious link that redirects a victim to a credential-harvesting page. The domains behind those pages are short-lived — most are registered, weaponized, and abandoned within 48 hours — which means static blocklists go stale almost immediately. Effective protection requires a live, curated feed of domains that are confirmed active right now, not a snapshot from last month.
        
        The PhishingDetectionAPI service addresses this by ingesting domains from curated threat-intelligence feeds — including community-driven sources such as phish.co.za and other OSINT providers — every 24 hours. Each domain undergoes DNS verification to confirm it is still resolving, which eliminates the false-positive noise of stale entries. Domains that stop resolving are automatically pruned, so the database reflects the current threat landscape rather than an ever-growing graveyard of expired campaigns.
        
        ---
        
        ## Installation
        
        ```bash
        pip install phishingdetectionapi
        ```
        
        The only runtime dependency is [`requests`](https://requests.readthedocs.io/). Python 3.7 and newer are supported.
        
        ## Quick start
        
        ```python
        from phishingdetectionapi import PhishingDetectionClient
        
        client = PhishingDetectionClient("your_api_key_here")
        
        # Check a single domain
        result = client.check("suspicious-login.example.com")
        print(result["is_phishing"])      # True
        print(result["category"])         # "phishing/malware"
        print(result["confidence"])       # 0.97
        print(result["dns_active"])       # True
        
        # Quick policy gate
        if result["is_phishing"]:
            block_request("suspicious-login.example.com")
        ```
        
        An API key is required and can be obtained by registering at [phishingdetectionapi.com](https://www.phishingdetectionapi.com). Keys are passed as a query parameter on every request.
        
        ## API methods
        
        ### `check(domain)`
        
        Query a single domain against the phishing database. Pass a bare domain — `suspicious-site.com`, not `https://suspicious-site.com/page`. Returns an immediate verdict with no ambiguity: the `is_phishing` field is a boolean you can branch on directly.
        
        ```python
        result = client.check("paypal-verify-account.example.com")
        ```
        
        **Response:**
        
        ```json
        {
          "domain": "paypal-verify-account.example.com",
          "is_phishing": true,
          "category": "phishing/malware",
          "confidence": 0.97,
          "dns_active": true,
          "first_seen": "2026-07-18",
          "source": "osint",
          "status": 200
        }
        ```
        
        A domain that is not in the database returns `"is_phishing": false` with a 200 status — your integration checks one field instead of interpreting HTTP error codes.
        
        ### `bulk_check(domains)`
        
        Submit up to 1,000 domains in a single request. Ideal for scanning email logs, proxy logs, or SIEM alert queues in batch.
        
        ```python
        domains = ["suspicious-bank.example.com", "legitimate-site.com", "phish-attempt.example.net"]
        report = client.bulk_check(domains)
        
        for entry in report["results"]:
            if entry["is_phishing"]:
                print(f"BLOCKED: {entry['domain']} — {entry['category']}")
        ```
        
        ### `feed(date=None, format="json")`
        
        Retrieve the full daily threat feed or a specific date's snapshot. Use this to seed a local database, DNS sinkhole, or firewall blocklist.
        
        ```python
        # Today's full feed
        today_feed = client.feed()
        
        # Specific date
        historical = client.feed(date="2026-07-15")
        
        # CSV format for firewall ingestion
        csv_feed = client.feed(format="csv")
        ```
        
        The feed endpoint supports both JSON and CSV formats. CSV output can be imported directly into DNS resolvers, firewall External Dynamic Lists (EDLs), or SIEM lookup tables without any transformation.
        
        ### `stats()`
        
        Returns current database statistics — total active domains, domains added in the last 24 hours, domains pruned, and category breakdowns.
        
        ```python
        stats = client.stats()
        print(f"Active phishing domains: {stats['total_active']}")
        print(f"Added today: {stats['added_24h']}")
        print(f"Pruned (no longer resolving): {stats['pruned_24h']}")
        ```
        
        ## Error handling
        
        The client raises a small, specific exception hierarchy:
        
        ```python
        from phishingdetectionapi import PhishingDetectionClient
        from phishingdetectionapi.client import (
            PhishingDetectionError,
            AuthenticationError,
            RateLimitError,
        )
        
        try:
            result = client.check("example.com")
        except AuthenticationError:
            # 401 — API key invalid or expired
            rotate_api_key()
        except RateLimitError:
            # 429 — slow down or upgrade plan
            backoff_and_retry()
        except PhishingDetectionError as e:
            # Any other API or network failure
            log_error(e)
        ```
        
        The client is also a context manager, so the underlying HTTP session is cleaned up automatically:
        
        ```python
        with PhishingDetectionClient("your_api_key_here") as client:
            result = client.check("suspicious.example.com")
        ```
        
        ## Integration patterns
        
        ### Email gateway / MTA plugin
        
        Intercept inbound mail at the MTA layer and check every URL extracted from message bodies and headers against the phishing database before delivery:
        
        ```python
        from phishingdetectionapi import PhishingDetectionClient
        import re
        
        client = PhishingDetectionClient("your_api_key_here")
        
        def scan_email(raw_message):
            urls = re.findall(r'https?://([^/\s"\']+)', raw_message)
            domains = list(set(urls))
            if not domains:
                return True  # no URLs, deliver
        
            results = client.bulk_check(domains)
            threats = [r for r in results["results"] if r["is_phishing"]]
            if threats:
                quarantine_message(raw_message, threats)
                return False
            return True
        ```
        
        ### Proxy or browser extension
        
        Wrap the lookup in a lightweight middleware that intercepts HTTP requests before they leave the network:
        
        ```python
        def should_allow(domain):
            result = client.check(domain)
            if result["is_phishing"]:
                return False, f"Blocked: known phishing domain ({result['category']})"
            return True, None
        ```
        
        ### SIEM / SOAR playbook
        
        Feed the daily threat list into your SIEM as a lookup table, then trigger automated containment when a match fires:
        
        ```python
        def refresh_siem_indicators():
            feed = client.feed(format="json")
            for entry in feed["domains"]:
                siem_client.add_indicator(
                    value=entry["domain"],
                    type="domain",
                    threat_type=entry["category"],
                    confidence=entry["confidence"],
                )
        ```
        
        ### DNS sinkhole
        
        Export the feed to a flat file and load it into your DNS resolver (BIND RPZ, Pi-hole, AdGuard, Unbound) for network-wide protection:
        
        ```python
        with PhishingDetectionClient("your_api_key_here") as client:
            feed = client.feed(format="json")
            with open("/etc/bind/rpz/phishing.zone", "w") as fh:
                for entry in feed["domains"]:
                    fh.write(f"{entry['domain']} CNAME .\n")
        ```
        
        ## Why domain-level phishing detection matters
        
        Traditional anti-phishing defenses rely on content analysis — scanning email bodies for suspicious language, checking for lookalike logos, or running URLs through a sandbox. These methods are valuable but slow: by the time a sandbox renders a page, hundreds of victims may have already submitted credentials. Domain-level detection operates upstream of content. If the domain itself is a known phishing host, you can block the connection before any content is loaded, any form is rendered, or any credential is at risk.
        
        The speed advantage is significant. A single DNS or HTTP-layer lookup against a curated domain list adds negligible latency — typically under 5 milliseconds for a local cache hit — compared to the seconds required for full-page rendering and heuristic analysis. For high-volume environments such as email gateways processing millions of messages per day, or DNS resolvers handling billions of queries, that difference determines whether protection is practical at scale.
        
        ### The evolving phishing landscape
        
        Phishing campaigns have grown more sophisticated in recent years. Attackers now register domains that closely mimic legitimate brands, often using internationalized domain names (IDN homograph attacks), typosquatting, or subdomain abuse to evade casual inspection. A domain like `paypa1-secure-login.com` looks plausible at a glance in a mobile email client, and by the time a user realizes the deception, their credentials have already been harvested.
        
        Bulk domain registration services and automated phishing kits have lowered the barrier to entry. A single threat actor can register hundreds of domains in a day, deploy templated credential-harvesting pages, and rotate through them as each domain gets flagged. This churn rate is what makes static, manually curated blocklists ineffective — they cannot keep pace with the volume of new domains entering the threat landscape daily.
        
        The PhishingDetectionAPI database is rebuilt every 24 hours specifically to match this pace. Domains are sourced from multiple threat-intelligence feeds, deduplicated, categorized, and DNS-verified before they enter the active database. When a domain stops resolving — typically because the hosting provider or registrar has taken it down — it is pruned automatically so that the database reflects only current, active threats.
        
        ### Industry use cases
        
        Organizations across industries are adopting domain-level phishing intelligence. E-commerce platforms use it to block fake storefront pages that impersonate their checkout flows and steal payment credentials. Healthcare providers deploy it to protect patient portals from credential-harvesting campaigns that target sensitive medical records. Financial institutions integrate it into their transaction-monitoring pipelines to flag suspicious redirects in real time before customers are exposed to fraudulent login pages. Managed security service providers (MSSPs) bundle it into their SOC playbooks for automated triage, reducing mean time to response from hours to seconds. Educational institutions use it alongside their web filtering infrastructure to protect students and staff from phishing campaigns that target university credentials.
        
        The [phishing detection API](https://www.phishingdetectionapi.com) provides the data layer for all of these use cases, and this Python package provides the integration.
        
        ---
        
        ## Related services
        
        Organizations building layered security and content-filtering infrastructure may also benefit from these complementary services:
        
        * **[Website Categorization API](https://www.websitecategorizationapi.com):** Classify any URL or domain into IAB content categories, detect malware and social engineering, and enrich with metadata including technologies used, buyer personas, and sentiment analysis. Supports 150 languages and 700+ IAB categories.
        
        * **[AI Tools Blocklist](https://www.aitoolsblocklist.com):** A daily-refreshed database of tens of thousands of classified AI-tool domains — chatbots, code assistants, image generators, voice cloners — organized into functional categories for granular acceptable-use policies. Essential for enterprises and schools controlling data exposure through generative AI.
        
        * **[CIPA Web Filtering](https://www.cipawebfiltering.com):** A categorized domain database of 120M+ domains designed for K-12 schools, districts, and libraries to meet Children's Internet Protection Act compliance. Supports 57+ content categories with multi-label classification delivered via API, CSV, DNS/RPZ, PAC files, and firewall EDLs.
        
        * **[Web Filtering Database](https://www.webfilteringdatabase.com):** An enterprise-grade downloadable dataset of 100 million domains organized into 59 categories for DNS-level blocking, covering adult content, malware, gambling, social media, streaming, and other policy-relevant verticals.
        
        * **[URL Categorization Database](https://www.urlcategorizationdatabase.com):** Comprehensive categorized domain data at enterprise scale, covering IAB content taxonomy, ad-tech verticals, and e-commerce classifications for contextual targeting, brand safety, and large-scale analytics.
        
        ---
        
        ## Links
        
        - Product and API documentation: [https://www.phishingdetectionapi.com](https://www.phishingdetectionapi.com)
        - APWG Phishing Activity Trends: [https://apwg.org/](https://apwg.org/)
        - NIST Phishing Guidance: [https://www.nist.gov/](https://www.nist.gov/)
        - OWASP Phishing: [https://owasp.org/](https://owasp.org/)
        
        ## License
        
        MIT
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Requires-Python: >=3.7
Description-Content-Type: text/markdown
