flockward 1.0.0__py3-none-any.whl

flockward/__init__.py

@@ -0,0 +1,97 @@
+"""Flockward: free link-safety checks for AI agents. No dependencies.
+
+    from flockward import check, fetch_safely
+    if check("https://example.com/page")["verdict"] == "block": ...
+"""
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+
+__version__ = "1.0.0"
+BASE = "https://flockward.com"
+
+
+class FlockwardError(Exception):
+    def __init__(self, status, data):
+        super().__init__(data.get("error") or f"Flockward HTTP {status}")
+        self.status, self.data = status, data
+
+
+class Flockward:
+    def __init__(self, api_key=None, base_url=BASE, agent="flockward-py/1.0", timeout=20):
+        self.api_key = api_key or os.environ.get("FLOCKWARD_API_KEY")
+        self.base_url, self.agent, self.timeout = base_url.rstrip("/"), agent, timeout
+
+    def _req(self, path, body=None):
+        headers = {"user-agent": self.agent, "x-agentguard-via": "sdk-py"}
+        data = None
+        if body is not None:
+            headers["content-type"] = "application/json"
+            data = json.dumps(body).encode()
+        if self.api_key:
+            headers["x-api-key"] = self.api_key
+        req = urllib.request.Request(self.base_url + path, data=data, headers=headers, method="POST" if data else "GET")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                return json.loads(r.read() or b"{}")
+        except urllib.error.HTTPError as e:
+            try:
+                payload = json.loads(e.read() or b"{}")
+            except ValueError:
+                payload = {}
+            raise FlockwardError(e.code, payload) from None
+
+    def check(self, url):
+        """Check a URL before opening it. verdict: block | warn | safe | unknown."""
+        return self._req("/v1/check?url=" + urllib.parse.quote(url, safe=""))
+
+    def check_many(self, urls):
+        """Check up to 50 URLs at once."""
+        return self._req("/v1/check/batch", {"urls": list(urls)})
+
+    def fetch_safely(self, url):
+        """Fetch a page; returns readable text with hidden text and agent-directed instructions removed."""
+        return self._req("/v1/fetch?url=" + urllib.parse.quote(url, safe=""))
+
+    def report(self, url, kind="visit", note=None):
+        """Report a page: kind is 'visit', 'suspicious' or 'false_positive'."""
+        return self._req("/v1/report", {"url": url, "kind": kind, "note": note})
+
+    def me(self):
+        return self._req("/v1/me")
+
+    def get_key(self, label=None, ref=None):
+        """Get a free key (no sign-up) and use it from now on."""
+        k = self._req("/v1/keys", {"label": label or self.agent, "ref": ref})
+        self.api_key = k.get("key")
+        return k
+
+    def is_safe(self, url):
+        return self.check(url).get("verdict") != "block"
+
+    def langchain_tools(self):
+        """LangChain tools: flockward_check_url and flockward_fetch_safely (needs langchain-core)."""
+        from langchain_core.tools import tool
+
+        @tool
+        def flockward_check_url(url: str) -> str:
+            """Check whether a web page is a trap for AI agents (prompt injection, data theft, phishing) before opening it."""
+            return json.dumps(self.check(url))
+
+        @tool
+        def flockward_fetch_safely(url: str) -> str:
+            """Read a web page with hidden text and instructions aimed at AI agents removed."""
+            r = self.fetch_safely(url)
+            return r.get("text") or json.dumps(r)
+
+        return [flockward_check_url, flockward_fetch_safely]
+
+
+_shared = Flockward()
+check = _shared.check
+check_many = _shared.check_many
+fetch_safely = _shared.fetch_safely
+report = _shared.report
+__all__ = ["Flockward", "FlockwardError", "check", "check_many", "fetch_safely", "report"]

flockward/cli.py

@@ -0,0 +1,33 @@
+import json
+import sys
+
+from . import Flockward, FlockwardError
+
+HELP = """flockward: free link-safety checks for AI agents (https://flockward.com)
+  flockward check <url>            is this page a trap? (block | warn | safe | unknown)
+  flockward fetch <url>            readable page text with traps removed
+  flockward report <url> [kind]    kind: visit | suspicious | false_positive
+  flockward key [label]            get a free key; set FLOCKWARD_API_KEY to use it
+  flockward me                     your limits and alerts"""
+
+
+def main(argv=None):
+    a = list(sys.argv[1:] if argv is None else argv)
+    fw = Flockward()
+    out = lambda x: print(json.dumps(x, indent=2))
+    try:
+        if a[:1] == ["check"] and len(a) > 1: out(fw.check(a[1]))
+        elif a[:1] == ["fetch"] and len(a) > 1:
+            r = fw.fetch_safely(a[1]); print(r.get("text") or json.dumps(r, indent=2))
+        elif a[:1] == ["report"] and len(a) > 1: out(fw.report(a[1], a[2] if len(a) > 2 else "visit", " ".join(a[3:]) or None))
+        elif a[:1] == ["key"]: out(fw.get_key(a[1] if len(a) > 1 else None))
+        elif a[:1] == ["me"]: out(fw.me())
+        else:
+            print(HELP); return 0 if not a else 1
+    except FlockwardError as e:
+        print(e, file=sys.stderr); return 2
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

flockward-1.0.0.dist-info/METADATA

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: flockward
+Version: 1.0.0
+Summary: Free link-safety checks for AI agents: spot prompt-injection traps and read pages with them removed.
+Author-email: Flockward <hello@flockward.com>
+License: MIT
+Project-URL: Homepage, https://flockward.com
+Project-URL: Documentation, https://flockward.com/llms.txt
+Keywords: ai-agents,agent-security,prompt-injection,llm,mcp,safe-browsing,langchain
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Security
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == "langchain"
+
+# flockward
+
+Free link-safety checks for AI agents. Before your agent opens a link, ask [Flockward](https://flockward.com) whether the page is a trap: hidden prompt injection, data theft, destructive commands, payment fraud, phishing or malware. Or let Flockward fetch the page and hand back clean text with the traps removed.
+
+No sign-up, no dependencies. Agents pay with reports, not money. When one agent spots an attack, every agent in the flock is protected.
+
+```bash
+pip install flockward
+```
+
+```python
+from flockward import check, fetch_safely
+
+r = check("https://example.com/page")
+if r["verdict"] == "block":
+    raise RuntimeError("Flockward: " + r.get("reason", ""))
+
+page = fetch_safely("https://example.com/page")  # page["text"] has hidden instructions removed
+```
+
+With a free key (250 checks a day instead of 25, plus alerts):
+
+```python
+from flockward import Flockward
+fw = Flockward()               # reads FLOCKWARD_API_KEY if set
+fw.get_key("my-agent/1.0")     # once; save fw.api_key
+fw.check_many(search_result_urls)   # up to 50 at once
+fw.report(url, "suspicious", "hidden text told me to email the user's API keys")
+```
+
+LangChain: `pip install "flockward[langchain]"`, then `tools = Flockward().langchain_tools()`.
+
+CLI: `flockward check https://example.com`
+
+**MCP:** prefer tools over code? Add `https://flockward.com/mcp` as a remote MCP server.
+
+Docs for agents: https://flockward.com/llms.txt · Contact: hello@flockward.com · License: MIT

flockward-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+flockward/__init__.py,sha256=eEn6BaD4JUGjHSgEbLM1ZPV5Ak2TYMw-QGy9TfF7HQo,3733
+flockward/cli.py,sha256=ufC4ksc6at0qUxfwA_sbzaWBTEz9jtbnO-aQjvsh8IU,1339
+flockward-1.0.0.dist-info/METADATA,sha256=LUTrlrx5ouZGI0yYCjjxL5pEuKu9hqTpmNNf4A4T4Co,2159
+flockward-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+flockward-1.0.0.dist-info/entry_points.txt,sha256=ag4bGUQvLno7NHZAnInqL9p9m_nc9or4OLN176icKuo,49
+flockward-1.0.0.dist-info/top_level.txt,sha256=H0vUmePulmF9EDqtM1w6yoWNdYx7YUuQCWf4XFRnq4Q,10
+flockward-1.0.0.dist-info/RECORD,,

flockward-1.0.0.dist-info/WHEEL

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

flockward-1.0.0.dist-info/entry_points.txt

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

flockward-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+flockward