phishingdetectionapi 1.0.0__py3-none-any.whl

phishingdetectionapi/__init__.py

@@ -0,0 +1,4 @@
+from .client import PhishingDetectionClient
+
+__all__ = ["PhishingDetectionClient"]
+__version__ = "1.0.0"

phishingdetectionapi/client.py

@@ -0,0 +1,78 @@
+import requests
+
+
+class PhishingDetectionError(Exception):
+    pass
+
+
+class AuthenticationError(PhishingDetectionError):
+    pass
+
+
+class RateLimitError(PhishingDetectionError):
+    pass
+
+
+class PhishingDetectionClient:
+    def __init__(self, api_key, base_url="https://phishingdetectionapi.com/api/v1", timeout=30):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers.update({
+            "User-Agent": "phishingdetectionapi-python/1.0.0",
+            "Accept": "application/json",
+            "Accept-Encoding": "gzip",
+        })
+
+    def check(self, domain):
+        return self._get("/check", params={"domain": domain})
+
+    def bulk_check(self, domains):
+        return self._post("/bulk-check", json={"domains": domains})
+
+    def feed(self, date=None, format="json"):
+        params = {"format": format}
+        if date:
+            params["date"] = date
+        return self._get("/feed", params=params)
+
+    def stats(self):
+        return self._get("/stats")
+
+    def _get(self, path, params=None):
+        if params is None:
+            params = {}
+        params["apikey"] = self.api_key
+        resp = self.session.get(
+            f"{self.base_url}{path}",
+            params=params,
+            timeout=self.timeout,
+        )
+        return self._handle_response(resp)
+
+    def _post(self, path, json=None):
+        if json is None:
+            json = {}
+        json["apikey"] = self.api_key
+        resp = self.session.post(
+            f"{self.base_url}{path}",
+            json=json,
+            timeout=self.timeout,
+        )
+        return self._handle_response(resp)
+
+    def _handle_response(self, resp):
+        if resp.status_code == 401:
+            raise AuthenticationError("Invalid or expired API key")
+        if resp.status_code == 429:
+            raise RateLimitError("Rate limit exceeded — back off or upgrade your plan")
+        if resp.status_code >= 400:
+            raise PhishingDetectionError(f"API error {resp.status_code}: {resp.text}")
+        return resp.json()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.session.close()

phishingdetectionapi-1.0.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alpha Quantum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

phishingdetectionapi-1.0.0.dist-info/METADATA

@@ -0,0 +1,275 @@
+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
+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
+Requires-Dist: requests
+
+# 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
+
+

phishingdetectionapi-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+phishingdetectionapi/__init__.py,sha256=klumj9teCxL99x9Vpqg0E72PAxtOmwUfmGf1lJEs30c,105
+phishingdetectionapi/client.py,sha256=4lZ8tfQc8mCYCpeR_C_wEDKzmimtnLppzsnyzRTwFXM,2243
+phishingdetectionapi-1.0.0.dist-info/LICENSE,sha256=-kjrwollysEMZkPQkJIq5zyefl9XyPw5egz8knSXiB4,1070
+phishingdetectionapi-1.0.0.dist-info/METADATA,sha256=qZX9t_lYllwBQ4vU_Or5fW2B34KNWVtarp_FoF0miaU,13616
+phishingdetectionapi-1.0.0.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
+phishingdetectionapi-1.0.0.dist-info/top_level.txt,sha256=GJsAq0jsrgARyAjreLOCBCCEoyKKSJ0DIcFkAcOkXXY,21
+phishingdetectionapi-1.0.0.dist-info/RECORD,,

phishingdetectionapi-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.45.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

phishingdetectionapi-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+phishingdetectionapi