shadowaitools 1.0.0__py3-none-any.whl

shadowaitools/__init__.py

@@ -0,0 +1,22 @@
+"""
+shadowaitools: local shadow AI inventory from DNS, proxy and firewall exports.
+
+    from shadowaitools import scan, to_csv
+    inv = scan("umbrella.csv", api_key="...")
+    print(inv["summary"]["ai_tools_found"])
+
+Hosted audit with the per-user breakdown, dated vendor training verdicts,
+sanctioned split and PDF evidence pack: https://www.shadowaitools.com
+"""
+
+from .client import (AuthenticationError, Client, QuotaError, RateLimitError, ShadowAIToolsError)
+from .inventory import scan, to_csv, to_table
+from .parser import (CLIENT_KEYS, DOMAIN_KEYS, extract_domains, norm_host, parse_log, registrable_domain)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "scan", "to_csv", "to_table", "parse_log", "extract_domains", "registrable_domain", "norm_host",
+    "Client", "ShadowAIToolsError", "AuthenticationError", "QuotaError", "RateLimitError",
+    "DOMAIN_KEYS", "CLIENT_KEYS", "__version__",
+]

shadowaitools/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

shadowaitools/cli.py

@@ -0,0 +1,107 @@
+"""Command line: shadowaitools scan <file> [options]."""
+
+import argparse
+import json
+import os
+import sys
+
+from . import __version__
+from .inventory import scan, to_csv, to_table
+from .parser import extract_domains, parse_log
+
+FORMATS = """csv          any delimited export with a header row; hostname column named domain, query, hostname, host, url, dest, destination, fqdn, site, sni or question
+key-value    syslog lines such as hostname="..." user="..." (Fortinet, SonicWall, Check Point, Sophos)
+dnsmasq      Pi-hole and dnsmasq query logs
+squid        Squid access.log (CONNECT host:443 lines)
+windows-dns  Windows DNS Server debug log packets
+generic      anything else: first hostname on each line, first private IP as the client
+"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="shadowaitools",
+        description="Shadow AI inventory from a DNS, proxy or firewall export. "
+                    "Hosted audit with per-user breakdown, training verdicts and PDF evidence pack: "
+                    "https://www.shadowaitools.com",
+    )
+    p.add_argument("--version", action="version", version="shadowaitools %s" % __version__)
+    sub = p.add_subparsers(dest="command")
+
+    s = sub.add_parser("scan", help="parse an export and look up every unique domain")
+    s.add_argument("file")
+    s.add_argument("--key", help="AI Tools Blocklist API key (or env SHADOWAITOOLS_API_KEY / ATB_API_KEY)")
+    s.add_argument("--json", help="write the inventory as JSON")
+    s.add_argument("--csv", help="write the inventory as CSV")
+    s.add_argument("--cache", help="reuse and extend a JSON cache of previous lookups")
+    s.add_argument("--sanctioned", help="comma-separated domains counted as sanctioned")
+    s.add_argument("--max-lines", type=int)
+    s.add_argument("--concurrency", type=int, default=1)
+    s.add_argument("--pause", type=float, default=0.0, help="seconds between lookups")
+    s.add_argument("--quiet", action="store_true", help="print only the table")
+
+    d = sub.add_parser("domains", help="list unique registrable domains without any lookup")
+    d.add_argument("file")
+    d.add_argument("--max-lines", type=int)
+
+    sub.add_parser("formats", help="show the accepted export formats")
+    return p
+
+
+def main(argv=None) -> int:
+    p = build_parser()
+    args = p.parse_args(argv)
+    if not args.command:
+        p.print_help()
+        return 0
+    if args.command == "formats":
+        sys.stdout.write(FORMATS)
+        return 0
+    if not os.path.exists(args.file):
+        sys.stderr.write("file not found: %s\n" % args.file)
+        return 2
+    if args.command == "domains":
+        parsed = parse_log(args.file, max_lines=args.max_lines)
+        groups = extract_domains(parsed["records"])
+        sys.stdout.write("%s export, %d lines, %d unique domains\n" % (parsed["format"], parsed["lines"], len(groups)))
+        for g in groups:
+            sys.stdout.write("%7d  %s\n" % (g["hits"], g["domain"]))
+        return 0
+
+    key = args.key or os.environ.get("SHADOWAITOOLS_API_KEY") or os.environ.get("ATB_API_KEY")
+    if not key:
+        sys.stderr.write("An API key is required: --key KEY or SHADOWAITOOLS_API_KEY.\n")
+        return 2
+    shown = {"n": 0}
+
+    def progress(done, total):
+        if done == total or done - shown["n"] >= 25:
+            sys.stderr.write("looked up %d/%d domains\n" % (done, total))
+            shown["n"] = done
+
+    try:
+        inv = scan(
+            args.file, api_key=key, concurrency=args.concurrency, pause=args.pause, max_lines=args.max_lines,
+            cache_file=args.cache,
+            sanctioned=[x.strip() for x in (args.sanctioned or "").split(",") if x.strip()],
+            on_progress=None if args.quiet else progress,
+        )
+    except Exception as exc:  # surfaced as a one-line error for operators
+        sys.stderr.write("%s: %s\n" % (exc.__class__.__name__, exc))
+        return 1
+    if args.json:
+        with open(args.json, "w", encoding="utf-8") as fh:
+            json.dump(inv, fh, indent=2)
+    if args.csv:
+        with open(args.csv, "w", encoding="utf-8") as fh:
+            fh.write(to_csv(inv))
+    sys.stdout.write(to_table(inv) + "\n")
+    if args.json:
+        sys.stderr.write("JSON written to %s\n" % os.path.abspath(args.json))
+    if args.csv:
+        sys.stderr.write("CSV written to %s\n" % os.path.abspath(args.csv))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

shadowaitools/client.py

@@ -0,0 +1,98 @@
+"""
+Lookup client for the AI Tools Blocklist API.
+
+    GET https://www.aitoolsblocklist.com/api/check?domain=<domain>
+    header X-API-Key: <key>
+
+One lookup is charged per call. Subdomains resolve to their registrable
+domain on the server, so the client reduces hosts before sending them and
+never sends a full URL or any log line.
+"""
+
+import time
+from typing import Dict, Optional
+
+import requests
+
+from .parser import registrable_domain
+
+VERSION = "1.0.0"
+DEFAULT_BASE_URL = "https://www.aitoolsblocklist.com/api"
+DEFAULT_TIMEOUT = 30
+USER_AGENT = "shadowaitools-python/%s (+https://www.shadowaitools.com)" % VERSION
+
+
+class ShadowAIToolsError(Exception):
+    """Base exception. ``status`` and ``body`` carry the HTTP status and parsed body when known."""
+
+    def __init__(self, message: str, status: Optional[int] = None, body=None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class AuthenticationError(ShadowAIToolsError):
+    """401: missing or unknown API key."""
+
+
+class QuotaError(ShadowAIToolsError):
+    """403: account not active or the monthly lookup quota is exhausted."""
+
+
+class RateLimitError(ShadowAIToolsError):
+    """429: too many requests."""
+
+
+class Client:
+    """
+    Args:
+        api_key: AI Tools Blocklist API key, sent as X-API-Key.
+        base_url: override for testing.
+        timeout: per-request timeout in seconds.
+        max_retries: retries on 429 and 503 with a short pause.
+    """
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL, timeout: int = DEFAULT_TIMEOUT,
+                 max_retries: int = 2):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._session = requests.Session()
+        self._session.headers.update({
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+            "X-API-Key": api_key,
+        })
+
+    def lookup(self, domain: str) -> Dict:
+        """Classify one domain. ``blocked`` is True for a known AI tool; ``categories`` may hold several rows."""
+        d = registrable_domain(domain)
+        last = None
+        for attempt in range(self.max_retries + 1):
+            resp = self._session.get(self.base_url + "/check", params={"domain": d}, timeout=self.timeout)
+            if resp.status_code in (429, 503) and attempt < self.max_retries:
+                last = resp
+                time.sleep(1.5 * (attempt + 1))
+                continue
+            return self._handle(resp)
+        return self._handle(last)
+
+    @staticmethod
+    def _handle(resp) -> Dict:
+        try:
+            data = resp.json()
+        except ValueError:
+            data = {"message": resp.text[:200]}
+        if resp.status_code == 200:
+            return data
+        msg = data.get("message") or data.get("error") or "HTTP %s" % resp.status_code
+        if resp.status_code == 401:
+            raise AuthenticationError(msg, 401, data)
+        if resp.status_code == 403:
+            raise QuotaError(msg, 403, data)
+        if resp.status_code == 429:
+            raise RateLimitError(msg, 429, data)
+        raise ShadowAIToolsError("HTTP %s: %s" % (resp.status_code, msg), resp.status_code, data)

shadowaitools/inventory.py

@@ -0,0 +1,184 @@
+"""
+Build the shadow AI inventory: parse locally, look up each unique registrable
+domain once, and assemble tools, summary and per-category counts.
+"""
+
+import csv
+import io
+import json
+import os
+import time
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime, timezone
+from typing import Callable, Dict, Iterable, List, Optional
+
+from .client import Client
+from .parser import extract_domains, parse_log, registrable_domain
+
+TOOL_FIELDS = ("primary_category", "ai_type", "trains_on_data", "opt_out_available",
+               "enterprise_no_training", "api_no_training", "terms_checked")
+
+
+def _load_cache(path: Optional[str]) -> Dict:
+    if not path or not os.path.exists(path):
+        return {}
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            return json.load(fh)
+    except (OSError, ValueError):
+        return {}
+
+
+def _save_cache(path: Optional[str], cache: Dict) -> None:
+    if not path:
+        return
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(cache, fh, indent=1)
+
+
+def scan(source, api_key: Optional[str] = None, concurrency: int = 1, pause: float = 0.0,
+         max_lines: Optional[int] = None, cache_file: Optional[str] = None,
+         sanctioned: Optional[Iterable[str]] = None, on_progress: Optional[Callable[[int, int], None]] = None,
+         client: Optional[Client] = None, **client_options) -> Dict:
+    """
+    Parse an export and return the inventory dict.
+
+    Args:
+        source: path, contents string, bytes or file object.
+        api_key: AI Tools Blocklist key (or env SHADOWAITOOLS_API_KEY / ATB_API_KEY).
+        concurrency: parallel lookups (default 1).
+        pause: seconds to wait after each lookup.
+        max_lines: stop parsing after this many lines.
+        cache_file: JSON file of previous lookups, reused and extended.
+        sanctioned: domains counted as sanctioned in the split.
+        on_progress: callback(done, total).
+    """
+    key = api_key or os.environ.get("SHADOWAITOOLS_API_KEY") or os.environ.get("ATB_API_KEY")
+    if not key and client is None:
+        raise ValueError("api_key is required (or set SHADOWAITOOLS_API_KEY)")
+    client = client or Client(key, **client_options)
+    parsed = parse_log(source, max_lines=max_lines)
+    groups = extract_domains(parsed["records"])
+    cache = _load_cache(cache_file)
+    sanctioned_set = {registrable_domain(d) for d in (sanctioned or [])}
+    state = {"done": 0, "lookups": 0, "quota": None}
+
+    def resolve(group):
+        d = group["domain"]
+        res = cache.get(d)
+        if res is None:
+            res = client.lookup(d)
+            state["lookups"] += 1
+            cache[d] = res
+            if pause:
+                time.sleep(pause)
+        if isinstance(res, dict) and "quota_remaining" in res:
+            state["quota"] = res["quota_remaining"]
+        state["done"] += 1
+        if on_progress:
+            on_progress(state["done"], len(groups))
+        return res
+
+    if concurrency > 1:
+        with ThreadPoolExecutor(max_workers=concurrency) as pool:
+            results = list(pool.map(resolve, groups))
+    else:
+        results = [resolve(g) for g in groups]
+    _save_cache(cache_file, cache)
+
+    tools: List[Dict] = []
+    users_all = set()
+    for g, r in zip(groups, results):
+        r = r or {}
+        if not r.get("blocked"):
+            continue
+        for u in g["users"]:
+            users_all.add(u["name"])
+        tool = {
+            "domain": r.get("domain") or g["domain"],
+            "hosts": g["hosts"],
+            "hits": g["hits"],
+            "users": g["users"],
+            "sanctioned": g["domain"] in sanctioned_set,
+            "categories": r.get("categories") or [],
+        }
+        for f in TOOL_FIELDS:
+            tool[f] = r.get(f) if f in ("primary_category", "ai_type", "terms_checked") else (r.get(f) or "unstated")
+        tools.append(tool)
+    tools.sort(key=lambda t: (-t["hits"], t["domain"]))
+
+    by_category: Dict[str, int] = {}
+    for t in tools:
+        c = t["primary_category"] or (t["categories"][0]["category"] if t["categories"] else "Uncategorized")
+        by_category[c] = by_category.get(c, 0) + 1
+
+    return {
+        "generated": datetime.now(timezone.utc).isoformat(),
+        "format": parsed["format"],
+        "summary": {
+            "lines": parsed["lines"],
+            "records": len(parsed["records"]),
+            "unique_domains": len(groups),
+            "lookups": state["lookups"],
+            "ai_tools_found": len(tools),
+            "sanctioned": sum(1 for t in tools if t["sanctioned"]),
+            "unsanctioned": sum(1 for t in tools if not t["sanctioned"]),
+            "users_involved": len(users_all),
+            "training_default_yes": sum(1 for t in tools if t["trains_on_data"] in ("yes", "opt_out_default")),
+            "training_no": sum(1 for t in tools if t["trains_on_data"] == "no"),
+            "unstated": sum(1 for t in tools if t["trains_on_data"] == "unstated"),
+            "quota_remaining": state["quota"],
+        },
+        "by_category": by_category,
+        "tools": tools,
+    }
+
+
+def to_csv(inventory: Dict) -> str:
+    """One CSV row per AI tool."""
+    buf = io.StringIO()
+    w = csv.writer(buf, lineterminator="\n")
+    w.writerow(["domain", "hits", "users", "sanctioned", "primary_category", "categories", "ai_type",
+                "trains_on_data", "opt_out_available", "enterprise_no_training", "api_no_training",
+                "terms_checked", "hosts"])
+    for t in inventory["tools"]:
+        cats = "; ".join(
+            "%s / %s" % (c["category"], c["subcategory"]) if c.get("subcategory") else c["category"]
+            for c in t["categories"]
+        )
+        w.writerow([
+            t["domain"], t["hits"], "; ".join(u["name"] for u in t["users"]), "yes" if t["sanctioned"] else "no",
+            t["primary_category"] or "", cats, t["ai_type"] or "", t["trains_on_data"], t["opt_out_available"],
+            t["enterprise_no_training"], t["api_no_training"], t["terms_checked"] or "", "; ".join(t["hosts"]),
+        ])
+    return buf.getvalue()
+
+
+def to_table(inventory: Dict) -> str:
+    """Fixed-width text table for terminals and tickets."""
+    s = inventory["summary"]
+    out = [
+        "Shadow AI inventory (%s export, %d lines, %d unique domains, %d lookups)"
+        % (inventory["format"], s["lines"], s["unique_domains"], s["lookups"]),
+        "AI tools found: %d   users involved: %d   train on your data by default: %d   terms silent: %d"
+        % (s["ai_tools_found"], s["users_involved"], s["training_default_yes"], s["unstated"]),
+        "",
+    ]
+    cols = [("domain", 26), ("hits", 5), ("ai type", 10), ("category", 26), ("trains on data", 15),
+            ("sanctioned", 10), ("users", 22)]
+    out.append("  ".join(n.ljust(w) for n, w in cols))
+    out.append("  ".join("-" * w for _, w in cols))
+    for t in inventory["tools"]:
+        cat = t["primary_category"] or (t["categories"][0]["category"] if t["categories"] else "")
+        users = ", ".join(u["name"] for u in t["users"][:2])
+        if len(t["users"]) > 2:
+            users += " +%d" % (len(t["users"]) - 2)
+        out.append("  ".join([
+            t["domain"][:26].ljust(26), str(t["hits"]).ljust(5), str(t["ai_type"] or "")[:10].ljust(10),
+            cat[:26].ljust(26), t["trains_on_data"].ljust(15), ("yes" if t["sanctioned"] else "no").ljust(10),
+            users[:22].ljust(22),
+        ]))
+    out.append("")
+    out.append("Per-user breakdown, dated vendor training verdicts, sanctioned split and the PDF evidence pack: "
+               "https://www.shadowaitools.com")
+    return "\n".join(out)

shadowaitools/parser.py

@@ -0,0 +1,266 @@
+"""
+Local parsing of DNS, proxy and firewall exports.
+
+Nothing here touches the network. The export is read once, each line is
+reduced to a hostname (and a user, device or client IP when the export
+carries one), and hostnames are grouped by registrable domain.
+
+Formats detected from the first non-empty line:
+
+    csv          delimited export with a header row (comma, tab, semicolon, pipe)
+    key-value    syslog style hostname="..." user="..." lines
+    dnsmasq      Pi-hole and dnsmasq query logs
+    squid        Squid access.log
+    windows-dns  Windows DNS Server debug log packets
+    generic      first hostname on each line, first private IP as the client
+"""
+
+import csv
+import io
+import os
+import re
+from collections import OrderedDict
+from typing import Dict, Iterable, List, Optional
+
+HOST_RE = re.compile(
+    r"(?<![\w.:/-])((?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+(?:[a-z]{2,24}|xn--[a-z0-9]{2,40}))\.?(?![\w-])",
+    re.I,
+)
+IP_RE = re.compile(r"(?<![\d.])((?:25[0-5]|2[0-4]\d|1?\d?\d)(?:\.(?:25[0-5]|2[0-4]\d|1?\d?\d)){3})(?![\d.])")
+PRIVATE_IP_RE = re.compile(
+    r"^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|127\.|169\.254\.|100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.)"
+)
+SKIP_TLD_RE = re.compile(r"\.(local|localdomain|internal|lan|home|arpa|corp|intranet|test|example|invalid)$")
+SKIP_HOST_RE = re.compile(r"^(www\.)?(w3\.org|schema\.org|xmlsoap\.org)$")
+KV_RE = re.compile(r'(\w+)=("([^"]*)"|(\S+))')
+WINDOWS_NAME_RE = re.compile(r"\(\d+\)[a-z0-9-]+(?:\(\d+\)[a-z0-9-]*)+\(0\)", re.I)
+
+DOMAIN_KEYS = [
+    "domain", "query", "query name", "query_name", "queryname", "hostname", "host", "url", "dest",
+    "destination", "dst", "dsthost", "dst_host", "fqdn", "site", "request", "name", "sni", "server name",
+    "domain name", "domainname", "question",
+]
+CLIENT_KEYS = [
+    "client", "client_ip", "client ip", "clientip", "src", "srcip", "src_ip", "source", "source ip",
+    "source address", "internal ip", "internalip", "identities", "identity", "device", "device name",
+    "device_name", "user", "username", "user name", "login", "endpoint", "computer", "workstation", "cip",
+    "requester", "from", "source user", "email",
+]
+KV_HOST_KEYS = ["hostname", "domain", "url", "dstname", "dsthost", "query", "fqdn", "sni", "site"]
+KV_CLIENT_KEYS = ["user", "usr", "srcname", "devname", "device", "login", "srcip", "src", "client", "clientip"]
+
+SECOND_LEVEL = {
+    "co.uk", "org.uk", "me.uk", "ac.uk", "gov.uk", "net.uk", "com.au", "net.au", "org.au", "edu.au", "co.nz",
+    "org.nz", "co.za", "co.in", "net.in", "org.in", "com.br", "net.br", "com.mx", "co.jp", "ne.jp", "or.jp",
+    "co.kr", "com.cn", "net.cn", "org.cn", "com.tw", "com.sg", "com.my", "co.id", "com.hk", "com.tr", "com.ar",
+    "com.co", "com.pe", "com.ve", "com.ua", "co.il", "com.eg", "co.ke", "com.ng", "com.pk", "com.bd", "com.pl",
+    "com.pt", "com.es", "com.de", "com.fr", "com.it", "com.ru", "github.io", "gitlab.io", "vercel.app",
+    "netlify.app", "herokuapp.com", "azurewebsites.net", "cloudfront.net", "amazonaws.com", "web.app",
+    "firebaseapp.com", "pages.dev", "workers.dev", "hf.space", "streamlit.app", "replit.app", "onrender.com",
+    "fly.dev", "railway.app", "glitch.me", "ngrok.io", "notion.site", "webflow.io",
+}
+
+
+def norm_host(value: str) -> str:
+    """Lower-case a hostname, strip scheme, path, port and surrounding punctuation."""
+    s = str(value or "").strip().lower().strip(" \t\r\n\"'<>[](),;")
+    s = re.sub(r"^[a-z][a-z0-9+.-]*://", "", s)
+    s = re.sub(r"[/?#].*$", "", s)
+    s = re.sub(r":\d+$", "", s)
+    return s.rstrip(".")
+
+
+def is_private_ip(ip: str) -> bool:
+    return bool(PRIVATE_IP_RE.match(ip))
+
+
+def skip_host(h: str) -> bool:
+    if not h or len(h) > 253:
+        return True
+    if SKIP_TLD_RE.search(h):
+        return True
+    return bool(SKIP_HOST_RE.match(h))
+
+
+def is_host(h: str) -> bool:
+    m = HOST_RE.search(" " + h + " ")
+    return bool(m) and norm_host(m.group(1)) == h
+
+
+def registrable_domain(host: str) -> str:
+    """chat.openai.com -> openai.com; news.bbc.co.uk -> bbc.co.uk; user.github.io stays three labels."""
+    h = norm_host(host)
+    labels = h.split(".")
+    if len(labels) <= 2:
+        return h
+    last_two = ".".join(labels[-2:])
+    if last_two in SECOND_LEVEL:
+        return ".".join(labels[-3:])
+    return last_two
+
+
+def _decode_windows_name(s: str) -> str:
+    parts = []
+    for count, label in re.findall(r"\((\d+)\)([^()\s]*)", s):
+        if count == "0":
+            break
+        parts.append(label)
+    return ".".join(parts)
+
+
+def _detect(first: str) -> Dict:
+    for d in (",", "\t", ";", "|"):
+        if first.count(d) >= 2:
+            cells = [c.strip().strip("\"'").lower() for c in next(csv.reader([first], delimiter=d))]
+            dc = cc = None
+            for i, c in enumerate(cells):
+                if dc is None and c in DOMAIN_KEYS:
+                    dc = i
+                if cc is None and c in CLIENT_KEYS:
+                    cc = i
+            if dc is not None:
+                return {"format": "csv", "delim": d, "domain_col": dc, "client_col": cc, "header": True}
+    if re.search(r"\b(hostname|url|domain|srcip|dstip|dstname)=", first, re.I):
+        return {"format": "key-value"}
+    if re.search(r"dnsmasq|query\[A{1,4}\]", first, re.I):
+        return {"format": "dnsmasq"}
+    if re.match(r"^\d+\.\d+\s+\d+\s+\S+\s+TCP_", first):
+        return {"format": "squid"}
+    if re.search(r"\(\d+\)[a-z0-9-]+\(\d+\)", first, re.I) and "PACKET" in first.upper():
+        return {"format": "windows-dns"}
+    return {"format": "generic"}
+
+
+def _parse_kv(line: str) -> Dict[str, str]:
+    out = {}
+    for key, _, quoted, bare in KV_RE.findall(line):
+        out[key.lower()] = quoted if quoted else bare
+    return out
+
+
+def _read_text(source) -> str:
+    if hasattr(source, "read"):
+        data = source.read()
+        return data.decode("utf-8", "replace") if isinstance(data, bytes) else data
+    if isinstance(source, bytes):
+        return source.decode("utf-8", "replace")
+    s = str(source)
+    if "\n" not in s and os.path.exists(s):
+        with open(s, "rb") as fh:
+            return fh.read().decode("utf-8", "replace")
+    return s
+
+
+def parse_log(source, max_lines: Optional[int] = None) -> Dict:
+    """
+    Parse an export given as a path, a string of contents, bytes or a file object.
+
+    Returns {"format": str, "lines": int, "records": [{"host": str, "user": str|None}, ...]}.
+    """
+    text = _read_text(source)
+    lines = text.splitlines()
+    first = None
+    first_idx = 0
+    for i, raw in enumerate(lines):
+        t = raw.strip()
+        if t and not t.startswith("#"):
+            first, first_idx = t, i
+            break
+    if first is None:
+        return {"format": "empty", "lines": 0, "records": []}
+    det = _detect(first)
+    fmt = det["format"]
+    records: List[Dict[str, Optional[str]]] = []
+    count = 0
+    start = first_idx + 1 if det.get("header") else first_idx
+    for raw in lines[start:]:
+        t = raw.strip()
+        if not t or t.startswith("#"):
+            continue
+        count += 1
+        if max_lines and count > max_lines:
+            break
+        host = None
+        user = None
+        if fmt == "csv":
+            cells = next(csv.reader([t], delimiter=det["delim"]))
+            raw_cell = cells[det["domain_col"]].strip() if det["domain_col"] < len(cells) else ""
+            cand = norm_host(raw_cell)
+            if not cand or not is_host(cand):
+                m = HOST_RE.search(" " + raw_cell + " ")
+                cand = norm_host(m.group(1)) if m else ""
+            host = cand
+            cc = det.get("client_col")
+            if cc is not None and cc < len(cells):
+                user = cells[cc].strip().strip("\"'")
+                if "," in user:
+                    user = user.split(",")[0].strip()
+        elif fmt == "key-value":
+            kv = _parse_kv(t)
+            for k in KV_HOST_KEYS:
+                if kv.get(k):
+                    host = norm_host(kv[k])
+                    break
+            for k in KV_CLIENT_KEYS:
+                if kv.get(k):
+                    user = kv[k]
+                    break
+        elif fmt == "dnsmasq":
+            m = re.search(r"query\[\w+\]\s+(\S+)\s+from\s+(\S+)", t, re.I)
+            if m:
+                host, user = norm_host(m.group(1)), m.group(2)
+        elif fmt == "squid":
+            parts = t.split()
+            user = parts[2] if len(parts) > 2 else None
+            host = norm_host(parts[6]) if len(parts) > 6 else None
+            if host and not is_host(host):
+                host = None
+            if len(parts) > 7 and parts[7] != "-" and not re.match(r"^[A-Z_]+/", parts[7]):
+                user = parts[7]
+        elif fmt == "windows-dns":
+            m = WINDOWS_NAME_RE.search(t)
+            if m:
+                host = norm_host(_decode_windows_name(m.group(0)))
+            for ip in IP_RE.findall(t):
+                if is_private_ip(ip):
+                    user = ip
+                    break
+        else:
+            for h in HOST_RE.findall(" " + t + " "):
+                n = norm_host(h)
+                if not skip_host(n):
+                    host = n
+                    break
+            for ip in IP_RE.findall(t):
+                if is_private_ip(ip):
+                    user = ip
+                    break
+        if not host or skip_host(host) or not is_host(host):
+            continue
+        if user and len(user) > 120:
+            user = None
+        records.append({"host": host, "user": user or None})
+    return {"format": fmt, "lines": count, "records": records}
+
+
+def extract_domains(records: Iterable[Dict]) -> List[Dict]:
+    """Group records by registrable domain: [{domain, hosts, hits, users:[{name, hits}]}] sorted by hits."""
+    groups: "OrderedDict[str, Dict]" = OrderedDict()
+    for r in records:
+        d = registrable_domain(r["host"])
+        g = groups.setdefault(d, {"domain": d, "hosts": set(), "hits": 0, "users": {}})
+        g["hosts"].add(r["host"])
+        g["hits"] += 1
+        if r.get("user"):
+            g["users"][r["user"]] = g["users"].get(r["user"], 0) + 1
+    out = []
+    for g in groups.values():
+        users = sorted(g["users"].items(), key=lambda kv: -kv[1])
+        out.append({
+            "domain": g["domain"],
+            "hosts": sorted(g["hosts"]),
+            "hits": g["hits"],
+            "users": [{"name": n, "hits": h} for n, h in users],
+        })
+    out.sort(key=lambda g: (-g["hits"], g["domain"]))
+    return out

shadowaitools-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.

shadowaitools-1.0.0.dist-info/METADATA

@@ -0,0 +1,336 @@
+Metadata-Version: 2.1
+Name: shadowaitools
+Version: 1.0.0
+Summary: Shadow AI detection from the logs you already have: parse a DNS, proxy or firewall export locally, look up each unique domain against the AI Tools Blocklist, and get an inventory of the AI tools in use with category, AI type and vendor training verdicts.
+Home-page: https://www.shadowaitools.com
+Author: Alpha Quantum
+Author-email: info@alpha-quantum.com
+License: MIT
+Project-URL: Homepage, https://www.shadowaitools.com
+Project-URL: Documentation, https://www.shadowaitools.com
+Project-URL: Source, https://github.com/explainableaixai/shadowaitools
+Project-URL: Tracker, https://www.shadowaitools.com/contact.php
+Project-URL: AI Tools Blocklist, https://www.aitoolsblocklist.com
+Project-URL: AI Agent Allow List, https://www.aiagentallowlist.com
+Project-URL: Shadow AI Tools, https://www.shadowaitools.com
+Keywords: shadow ai,shadow ai detection,shadow ai tools,shadow ai discovery,ai tools inventory,dns log analysis,proxy log analysis,firewall log,ai governance,ai acceptable use,data loss prevention,ai blocklist,generative ai usage,ai risk management
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests >=2.20.0
+
+# shadowaitools
+
+`shadowaitools` turns a DNS, proxy or firewall export into an inventory of the AI tools in use on your network. It runs on your own machine: the export is parsed locally, every hostname is reduced to its registrable domain, and each unique domain is looked up once against the [AI blocklist for web filtering](https://www.aitoolsblocklist.com) at aitoolsblocklist.com. What comes back is a list of tools with category, AI type, hit counts, the users or devices that reached them, and the vendor's position on training with your data, dated.
+
+It is the command line and Python counterpart of the hosted service at shadowaitools.com, which lets you [find the AI tools employees use](https://www.shadowaitools.com) from the same export in a browser and produces the per-user breakdown, the sanctioned versus unsanctioned split and a PDF evidence pack.
+
+Only `requests` is required. Python 3.7 and newer.
+
+---
+
+## Installation
+
+```bash
+pip install shadowaitools
+```
+
+This installs the `shadowaitools` command and the `shadowaitools` package. The API key is an AI Tools Blocklist key from the account area at aitoolsblocklist.com; pass it as `--key` or export it once:
+
+```bash
+export SHADOWAITOOLS_API_KEY=your_key
+```
+
+## Quick start
+
+```bash
+shadowaitools scan nextdns-export.csv --csv inventory.csv --json inventory.json
+```
+
+```
+Shadow AI inventory (csv export, 400 lines, 45 unique domains, 45 lookups)
+AI tools found: 34   users involved: 10   train on your data by default: 16   terms silent: 15
+
+domain                      hits   ai type     category                    trains on data   sanctioned  users
+--------------------------  -----  ----------  --------------------------  ---------------  ----------  ----------------------
+character.ai                10     ai_native   Text & Language             yes              no          laptop-marketing-02 +2
+openai.com                  10     ai_native   Code & Development          opt_out_default  yes         laptop-eng-07 +4
+otter.ai                    7      ai_native   Audio, Voice & Music        yes              no          laptop-sales-09 +2
+midjourney.com              5      ai_native   Image & Visual              unstated         no          laptop-exec-01 +1
+elevenlabs.io               4      ai_native   Text & Language             opt_out_default  no          laptop-eng-07 +1
+fireflies.ai                3      ai_native   Audio, Voice & Music        no               no          desktop-support-03 +1
+```
+
+In Python:
+
+```python
+from shadowaitools import scan, to_csv
+
+inventory = scan(
+    "zscaler-web.csv",
+    api_key="your_key",
+    sanctioned=["openai.com", "github.com"],
+    cache_file="lookups.json",
+)
+
+print(inventory["summary"])
+# {'lines': 400, 'records': 400, 'unique_domains': 45, 'lookups': 45, 'ai_tools_found': 34,
+#  'sanctioned': 2, 'unsanctioned': 32, 'users_involved': 10, 'training_default_yes': 16,
+#  'training_no': 3, 'unstated': 15, 'quota_remaining': 9999940}
+
+for tool in inventory["tools"]:
+    if not tool["sanctioned"] and tool["ai_type"] == "ai_native":
+        print(tool["domain"], tool["hits"], [u["name"] for u in tool["users"]], tool["trains_on_data"])
+
+with open("inventory.csv", "w") as fh:
+    fh.write(to_csv(inventory))
+```
+
+## How a scan works
+
+1. **Parse.** The first non-empty line decides the format. A header row with a known column name means CSV (comma, tab, semicolon or pipe). `hostname=` or `dstname=` tokens mean key=value syslog. `query[A]` means dnsmasq. The Squid `access.log` layout and Windows DNS Server debug packets have their own detectors. Anything else is read line by line for the first hostname and the first private IP address.
+2. **Reduce.** Each hostname becomes a registrable domain (`chat.openai.com` to `openai.com`, `news.bbc.co.uk` to `bbc.co.uk`). Names in reserved zones (`.local`, `.internal`, `.lan`, `.corp`, `.home`, `.arpa`, `.test`, `.example`) are dropped before anything is sent.
+3. **Look up.** Each unique domain is sent once to `GET https://www.aitoolsblocklist.com/api/check?domain=<domain>` with the key in the `X-API-Key` header. With `cache_file`, domains seen on a previous run are answered from the cache.
+4. **Assemble.** Domains with `blocked: true` become tools. Hits, hosts and users are attached from the parse, the sanctioned flag from your list, and the category, AI type and training fields from the lookup.
+
+A first run on a 400-line export with 45 distinct domains makes 45 lookups. A month of resolver logs with two million lines usually collapses to a few thousand registrable domains, because most traffic goes to a small set of hosts, and the second run through the same cache pays only for domains that are new that day. The `domains` command prints the exact count before any lookup is made.
+
+The user or device column is optional. When the export carries `Identities`, `user`, `Source User`, `device_name`, `client_ip`, `src` or a similar column, every tool lists who reached it; when it does not, the inventory still has the tools and the hit counts.
+
+## Accepted exports
+
+| Source | Format | Hostname column or field | User column or field |
+|---|---|---|---|
+| Cisco Umbrella activity export | csv | `Domain` | `Identities`, `Internal IP` |
+| Cloudflare Gateway DNS log | csv | `QueryName` | `DeviceName`, `SourceIP`, `Email` |
+| DNSFilter query log | csv | `domain` | `client`, `device` |
+| NextDNS log export | csv | `domain` | `client_ip`, `device_name` |
+| Palo Alto URL filtering log | csv | `URL` | `Source User`, `Source address` |
+| Zscaler web log | csv | `url` | `user`, `cip` |
+| Fortinet FortiGate web filter syslog | key-value | `hostname=` | `user=`, `srcip=` |
+| SonicWall syslog | key-value | `dstname=` | `usr=`, `src=` |
+| Pi-hole and dnsmasq | dnsmasq | `query[A] name` | `from address` |
+| Squid | squid | `CONNECT host:443` | client IP, authenticated user |
+| Windows DNS Server debug log | windows-dns | encoded question name | client address |
+| Plain hostname or URL list | generic | the line | none |
+| Any other text log | generic | first hostname on the line | first private IPv4 on the line |
+
+Anything with a header row and a hostname column works, whatever produced it. The `formats` command prints this list from the installed version.
+
+## API
+
+### `scan(source, api_key=None, **options)`
+
+`source` is a file path, a string of contents, `bytes` or an open file. Options:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `api_key` | env `SHADOWAITOOLS_API_KEY` or `ATB_API_KEY` | AI Tools Blocklist key |
+| `concurrency` | 1 | parallel lookups |
+| `pause` | 0.0 | seconds to wait after each lookup |
+| `max_lines` | none | stop parsing after this many lines |
+| `cache_file` | none | JSON file of previous lookups, reused and extended |
+| `sanctioned` | `[]` | domains to flag as sanctioned |
+| `on_progress` | none | callback `(done, total)` |
+| `timeout`, `max_retries`, `base_url` | 30, 2, production | passed to the client |
+
+Returns a dict with `generated`, `format`, `summary`, `by_category` and `tools`.
+
+### Tool fields
+
+| Field | Values |
+|---|---|
+| `domain`, `hosts`, `hits`, `users` | from the export |
+| `sanctioned` | `True` when the domain is in your list |
+| `primary_category` | one of 18 functional categories |
+| `categories` | `[{"category", "subcategory"}]`, a tool can sit in several |
+| `ai_type` | `ai_native` or `ai_enabled` |
+| `trains_on_data` | `yes`, `no`, `opt_out_default`, `unstated` |
+| `opt_out_available`, `enterprise_no_training`, `api_no_training` | same value set |
+| `terms_checked` | ISO date the vendor terms were last read |
+
+### Other functions
+
+| Function | Purpose |
+|---|---|
+| `parse_log(source, max_lines=None)` | `{"format", "lines", "records": [{"host", "user"}]}` with no network call |
+| `extract_domains(records)` | `[{"domain", "hosts", "hits", "users"}]` sorted by hits |
+| `registrable_domain(host)` | reduce a hostname |
+| `to_csv(inventory)` | one CSV row per tool |
+| `to_table(inventory)` | fixed-width text table |
+| `Client(api_key).lookup(domain)` | the raw lookup |
+
+### Exceptions
+
+`AuthenticationError` (401), `QuotaError` (403, inactive account or monthly quota used up), `RateLimitError` (429 after two retries) and the base `ShadowAIToolsError` (anything else, including 503 after retries). Each carries `.status` and `.body`.
+
+## Command line
+
+```
+shadowaitools scan <file> [--key KEY] [--json FILE] [--csv FILE] [--cache FILE]
+                          [--sanctioned a.com,b.com] [--max-lines N] [--concurrency N]
+                          [--pause SECONDS] [--quiet]
+shadowaitools domains <file>     unique registrable domains and hit counts, no lookups
+shadowaitools formats            the accepted export formats
+```
+
+`domains` is the dry run: it prints the format that was detected and the number of lookups a scan would need.
+
+## Worked examples
+
+### Weekly report for a security team
+
+```python
+# weekly_shadow_ai.py
+import datetime
+import json
+from shadowaitools import scan, to_csv
+
+week = datetime.date.today().isocalendar()[1]
+inv = scan(
+    f"/exports/umbrella-week-{week}.csv",
+    cache_file="/var/lib/shadowaitools/lookups.json",
+    sanctioned=open("/etc/shadowaitools/approved.txt").read().split(),
+    pause=0.05,
+)
+
+with open(f"/reports/shadow-ai-week-{week}.csv", "w") as fh:
+    fh.write(to_csv(inv))
+
+risky = [t for t in inv["tools"] if not t["sanctioned"] and t["trains_on_data"] in ("yes", "opt_out_default")]
+print(f"week {week}: {inv['summary']['ai_tools_found']} tools, {len(risky)} unsanctioned tools that train on input")
+for t in sorted(risky, key=lambda t: -t["hits"])[:10]:
+    print(f"  {t['domain']:28} {t['hits']:5} hits  {len(t['users']):3} users  {t['primary_category']}")
+```
+
+### Comparing two weeks
+
+```python
+from shadowaitools import scan
+
+before = scan("proxy-week-36.log", cache_file="lookups.json")
+after = scan("proxy-week-37.log", cache_file="lookups.json")
+
+seen_before = {t["domain"] for t in before["tools"]}
+new_tools = [t for t in after["tools"] if t["domain"] not in seen_before]
+print("new AI tools this week:", [t["domain"] for t in new_tools])
+```
+
+Because both scans share the cache, the second one only pays for domains that did not appear in the first.
+
+### Streaming a large export in chunks
+
+Exports from a busy resolver run to millions of lines. `parse_log` accepts a string, so a file can be read in blocks and grouped before a single lookup is made.
+
+```python
+from shadowaitools import Client, extract_domains, parse_log, registrable_domain
+
+records = []
+with open("dns-month.log", encoding="utf-8", errors="replace") as fh:
+    block = []
+    for line in fh:
+        block.append(line)
+        if len(block) == 200_000:
+            records.extend(parse_log("".join(block))["records"])
+            block = []
+    if block:
+        records.extend(parse_log("".join(block))["records"])
+
+groups = extract_domains(records)
+print(len(records), "records,", len(groups), "unique domains")
+
+client = Client("your_key")
+tools = []
+for g in groups:
+    r = client.lookup(g["domain"])
+    if r.get("blocked"):
+        tools.append((g["domain"], g["hits"], r.get("primary_category"), r.get("trains_on_data")))
+```
+
+### Only the lookup
+
+```python
+from shadowaitools import Client
+
+c = Client("your_key")
+print(c.lookup("chat.openai.com"))
+# {'domain': 'openai.com', 'blocked': True, 'primary_category': 'Code & Development', 'ai_type': 'ai_native',
+#  'categories': [...], 'trains_on_data': 'opt_out_default', 'opt_out_available': 'yes', ...}
+print(c.lookup("example.com")["blocked"])
+# False
+```
+
+## Why the logs are the right starting point
+
+Every governance framework begins with an inventory. The [NIST AI Risk Management Framework](https://www.nist.gov/itl/ai-risk-management-framework) puts "Map" before "Measure" and "Manage": an organisation has to know which AI systems are in use before any control can be applied. The [ENISA](https://www.enisa.europa.eu/) work on AI cybersecurity makes the same point for European organisations, and the [CISA](https://www.cisa.gov/) guidance on secure AI deployment assumes that operators can enumerate the AI services their people reach. On the data-protection side, the [ICO's guidance on AI and data protection](https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/artificial-intelligence/) treats the flow of personal data into third-party AI services as a processing activity that has to be documented.
+
+The inventory you need already exists in the DNS filter, proxy or firewall. It is complete in a way a survey can never be, it costs nothing to export, and it names the hostnames rather than the products people remember. The missing step is classification, which is what the lookup adds: is this domain an AI tool, what kind, and what does the vendor do with the input. Alongside the tool inventory, the same organisation usually wants the opposite control for its own agents, which is where an allow list for AI agents comes in: the [AI agent allow list](https://www.aiagentallowlist.com) tells a browsing agent which pages on a site it may open and which it must not, so the two datasets cover both directions of AI traffic.
+
+## Hosted audit
+
+The package produces the inventory. The hosted [shadow AI inventory](https://www.shadowaitools.com) at shadowaitools.com produces the report: upload the same export, get every tool with category and risk level, the per-user breakdown, dated training verdicts, the sanctioned split against your approved list, sector policy verdicts from the AI Policy Profiles, a CSV and a PDF evidence pack. The free preview names a fifth of the tools found and comes with a preview PDF; full reports are one-time purchases, and the subscription plans on aitoolsblocklist.com include one to ten audits a month.
+
+## Related packages
+
+- [`aiblocklist`](https://pypi.org/project/aiblocklist/) and [`aitoolsblocklist`](https://pypi.org/project/aitoolsblocklist/): Python clients for the lookup and feed APIs of the [AI domain blocklist](https://www.aitoolsblocklist.com), 20,000+ AI tool domains in 18 categories, refreshed daily, with EDL, PAC, hosts and DNS feeds.
+- [`aiagentallowlist`](https://pypi.org/project/aiagentallowlist/): per-URL allow, deny and flag verdicts for browsing agents across 40 million+ domains, up to 28 verified page types each.
+- [`websiteclassificationapi`](https://pypi.org/project/websiteclassificationapi/): the [website categorization API](https://www.websitecategorizationapi.com), 700+ IAB content categories for any URL.
+- [`cipawebfiltering`](https://pypi.org/project/cipawebfiltering/) and [`phishingdetectionapi`](https://pypi.org/project/phishingdetectionapi/): the [CIPA web filtering](https://www.cipawebfiltering.com) client for schools and the [phishing detection API](https://www.phishingdetectionapi.com) with 390,000+ DNS-verified active phishing domains.
+- The [web filtering database](https://www.webfilteringdatabase.com), 120M+ domains in 59 categories, for the same firewalls and resolvers.
+- Node.js: [`shadowaitools` on npm](https://www.npmjs.com/package/shadowaitools), same formats, same inventory, same cache file.
+- Source: [github.com/explainableaixai/shadowaitools](https://github.com/explainableaixai/shadowaitools) and [gitlab.com/url-classifications/shadowaitools](https://gitlab.com/url-classifications/shadowaitools).
+
+## Frequently asked questions
+
+**How do I detect shadow AI on my network?**
+Export a week of DNS, proxy or firewall logs, run `shadowaitools scan export.csv`, and read the inventory. Every hostname is matched against 20,000+ known AI tool domains, so the result is the AI traffic that actually crossed your network. For a report with the per-user breakdown and a PDF, upload the same file at [shadowaitools.com](https://www.shadowaitools.com).
+
+**Is anything installed on endpoints or inspected in transit?**
+No. The tool reads a log export that your DNS filter, proxy or firewall already produces. There is no agent, no TLS inspection and no change to the network.
+
+**Does the export leave my machine?**
+No. It is parsed locally. Only unique registrable domains are looked up, one request each, and reserved internal zones are never sent.
+
+**Which exports are supported?**
+Cisco Umbrella, Zscaler, Palo Alto, Fortinet, Cloudflare Gateway, DNSFilter, NextDNS, Pi-hole, SonicWall, Squid, Windows DNS Server debug logs, any CSV with a header row, key=value syslog lines and plain hostname lists. See the table above.
+
+**What is the difference between `ai_native` and `ai_enabled`?**
+`ai_native` is a service whose product is the AI: a chatbot, a code assistant, an image generator. `ai_enabled` is an ordinary product that has added AI features, such as an office suite with a built-in assistant. Both appear in the inventory because both can receive pasted content; the flag lets you treat them differently.
+
+**How current is the database behind the lookup?**
+It is rebuilt daily, with about 300,000 new domains checked every day against a 120-million-domain corpus, so new tools are caught close to launch. The training verdicts come from a review of 13,000+ vendor terms and carry the date they were checked.
+
+**Can I limit how many lookups a scan makes?**
+Yes. `shadowaitools domains file` shows the count first; `--max-lines` caps parsing; `--cache` makes repeated runs free for domains already seen; `--pause` slows the run down.
+
+**Who is behind shadowaitools?**
+Alpha Quantum, which also builds the [AI tools blocklist](https://www.aitoolsblocklist.com), the [AI agent allow list](https://www.aiagentallowlist.com), the [website categorization API](https://www.websitecategorizationapi.com) and the [web filtering database](https://www.webfilteringdatabase.com).
+
+## Links
+
+- Hosted shadow AI audit: [https://www.shadowaitools.com](https://www.shadowaitools.com)
+- The lookup database: [https://www.aitoolsblocklist.com](https://www.aitoolsblocklist.com)
+- AI agent allow list: [https://www.aiagentallowlist.com](https://www.aiagentallowlist.com)
+- NIST AI Risk Management Framework: [https://www.nist.gov/itl/ai-risk-management-framework](https://www.nist.gov/itl/ai-risk-management-framework)
+- ENISA: [https://www.enisa.europa.eu/](https://www.enisa.europa.eu/)
+- CISA: [https://www.cisa.gov/](https://www.cisa.gov/)
+- ICO, AI and data protection: [https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/artificial-intelligence/](https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/artificial-intelligence/)
+
+## License
+
+MIT

shadowaitools-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+shadowaitools/__init__.py,sha256=8YK1F6a9Ke8WnrqX-SALXmh2eesP82D6MjNye9Y98z4,896
+shadowaitools/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+shadowaitools/cli.py,sha256=Q9JJ04FwzzBRVyYb-9gbfySFg1RCqlZE8OJ6-VleQzY,4456
+shadowaitools/client.py,sha256=jruD60mOg-wVOpxegsdcV6TBA2aTcvFbPS0dcBbn4EA,3343
+shadowaitools/inventory.py,sha256=LmVQsmnLs9VLloa1d7yDjtulbLusqeaKpstjYSEqhKo,7661
+shadowaitools/parser.py,sha256=LZnU_t2waCZaCIzRy0xVy9-jHX78xLGKszeY3BuY3OY,10502
+shadowaitools-1.0.0.dist-info/LICENSE,sha256=-kjrwollysEMZkPQkJIq5zyefl9XyPw5egz8knSXiB4,1070
+shadowaitools-1.0.0.dist-info/METADATA,sha256=gBmfr5Suco7RIHi8nRTgDtHv4fhcrKTJM3Pie_qtJJE,20484
+shadowaitools-1.0.0.dist-info/WHEEL,sha256=BNRMDyzLkkcmlv0J8ppDQkk2VED33SesJDynr9ED1gc,91
+shadowaitools-1.0.0.dist-info/entry_points.txt,sha256=utczEx3srgMc1hVAilkKbDRRlly0QLmF21llmOYKrGU,57
+shadowaitools-1.0.0.dist-info/top_level.txt,sha256=WSKXw8XMllFV1xzLGtBuGNpHnd9lFmJv_Do8uK7KNgI,14
+shadowaitools-1.0.0.dist-info/RECORD,,

shadowaitools-1.0.0.dist-info/WHEEL

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

shadowaitools-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+shadowaitools = shadowaitools.cli:main

shadowaitools-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+shadowaitools