csa-secid 1.0.0__py3-none-any.whl

csa_secid-1.0.0.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: csa-secid
+Version: 1.0.0
+Summary: Resolve security identifiers to URLs using the SecID API
+Project-URL: Homepage, https://github.com/CloudSecurityAlliance/SecID
+Project-URL: Repository, https://github.com/CloudSecurityAlliance/SecID-Client-SDK
+Project-URL: Documentation, https://secid.cloudsecurityalliance.org
+Project-URL: Issues, https://github.com/CloudSecurityAlliance/SecID-Client-SDK/issues
+Author-email: Cloud Security Alliance <research@cloudsecurityalliance.org>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: cve,cybersecurity,secid,security,vulnerability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# secid
+
+Resolve security identifiers to URLs using the [SecID](https://secid.cloudsecurityalliance.org) API.
+
+SecID is a universal grammar for security knowledge — CVEs, CWEs, ATT&CK techniques, NIST controls, and more — maintained by the [Cloud Security Alliance](https://cloudsecurityalliance.org).
+
+**Zero dependencies.** Python 3.9+ stdlib only.
+
+## Install
+
+```bash
+pip install csa-secid
+```
+
+## CLI
+
+```bash
+# Resolve a CVE to its URL
+secid "secid:advisory/mitre.org/cve#CVE-2021-44228"
+
+# JSON output
+secid --json "secid:advisory/mitre.org/cve#CVE-2021-44228"
+
+# Cross-source search (find CVE across all advisory sources)
+secid "secid:advisory/CVE-2021-44228"
+```
+
+## Library
+
+```python
+from secid_client import SecIDClient
+
+client = SecIDClient()
+
+# Get the best URL for a security identifier
+url = client.best_url("secid:advisory/mitre.org/cve#CVE-2021-44228")
+print(url)  # https://www.cve.org/CVERecord?id=CVE-2021-44228
+
+# Full response with status, results, and guidance
+response = client.resolve("secid:advisory/mitre.org/cve#CVE-2021-44228")
+print(response.status)           # "found"
+print(response.best_url)         # highest-weight URL
+print(response.was_corrected)    # True if input was auto-corrected
+print(response.resolution_results)  # all URL results, sorted by weight
+print(response.registry_results)    # browsing/discovery data
+
+# Cross-source search
+response = client.lookup("advisory", "CVE-2021-44228")
+
+# Capability lookup (product security features)
+response = client.resolve("secid:capability/amazon.com/aws/s3#default-encryption")
+
+# Disclosure lookup (who to report vulnerabilities to)
+response = client.resolve("secid:disclosure/redhat.com/cna")
+
+# Look up a scoring methodology
+response = client.resolve("secid:methodology/first.org/cvss@4.0")
+```
+
+## SecID Format
+
+```
+secid:type/namespace/name[@version]#subpath
+```
+
+| Type | Identifies |
+|------|-----------|
+| `advisory` | Vulnerability publications (CVE, GHSA, vendor advisories) |
+| `weakness` | Abstract flaw patterns (CWE, OWASP Top 10) |
+| `ttp` | Adversary techniques (ATT&CK, CAPEC) |
+| `control` | Security requirements (NIST CSF, ISO 27001) |
+| `capability` | Product security features and capabilities |
+| `methodology` | Formal processes for producing security analysis |
+| `disclosure` | Vulnerability disclosure programs and reporting channels |
+| `regulation` | Laws (GDPR, HIPAA) |
+| `entity` | Organizations, products, services |
+| `reference` | Documents, research (arXiv, DOI, RFC) |
+
+## API
+
+One endpoint: `GET /api/v1/resolve?secid={encoded_secid}`
+
+The `#` character must be encoded as `%23` — the client handles this automatically.
+
+Resolution results may include optional format metadata fields: `content_type`, `parsability`, `schema`, `parsing_instructions`, and `auth`. These describe the data format at the resolved URL and are present only when the registry has documented them.
+
+## Links
+
+- [SecID Registry & Spec](https://github.com/CloudSecurityAlliance/SecID)
+- [SecID API + MCP Server](https://secid.cloudsecurityalliance.org)
+- [Cloud Security Alliance](https://cloudsecurityalliance.org)
+
+## License
+
+Apache 2.0

csa_secid-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+secid_client.py,sha256=gjEn5DNtSB-D4T7vDGejZqUzmxPK4u-nSVU6fczpYTg,12730
+csa_secid-1.0.0.dist-info/METADATA,sha256=OWie_CpBvItF2WUY41oxhzpdwTK2td7KnZspEsyTBZQ,4297
+csa_secid-1.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+csa_secid-1.0.0.dist-info/entry_points.txt,sha256=BJ8DmJx125mEDXPYIjyq1UGc6YD9Z7H-dhOgiNWBsGo,44
+csa_secid-1.0.0.dist-info/licenses/LICENSE,sha256=OSoLCoapvXQ9xOe9678SB5utika4uwbOBV8U2TQxsVw,10774
+csa_secid-1.0.0.dist-info/RECORD,,

csa_secid-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

csa_secid-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+secid = secid_client:main

csa_secid-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 Cloud Security Alliance
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

secid_client.py

@@ -0,0 +1,327 @@
+#!/usr/bin/env python3
+"""SecID client — resolve security identifiers to URLs.
+
+Single file, zero dependencies (stdlib only). Copy and use.
+
+SecID is a universal grammar for security knowledge:
+    secid:type/namespace/name[@version]#subpath
+
+API: GET https://secid.cloudsecurityalliance.org/api/v1/resolve?secid={encoded}
+
+IMPORTANT: The # character in SecID strings must be encoded as %23 in the
+URL query parameter. This is the #1 failure mode for new clients.
+
+Usage as library:
+    from secid_client import SecIDClient
+    client = SecIDClient()
+    response = client.resolve("secid:advisory/mitre.org/cve#CVE-2021-44228")
+    print(response.best_url)
+
+Usage as CLI:
+    secid "secid:advisory/mitre.org/cve#CVE-2021-44228"
+    secid --json "secid:advisory/mitre.org/cve#CVE-2021-44228"
+"""
+
+from __future__ import annotations
+
+# Single source of truth for the version: pyproject.toml reads it from here
+# (hatch dynamic version) and the User-Agent is built from it.
+__version__ = "1.0.0"
+
+import http.client
+import json
+import math
+import socket
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any
+
+DEFAULT_BASE_URL = "https://secid.cloudsecurityalliance.org"
+DEFAULT_TIMEOUT = 30  # seconds
+MAX_RESPONSE_BYTES = 10 * 1024 * 1024  # 10 MB
+
+
+@dataclass
+class SecIDResponse:
+    """Response from the SecID resolve API.
+
+    Attributes:
+        secid_query: The query string echoed back (decoded form).
+        status: One of: found, corrected, related, not_found, error.
+        results: List of result dicts — either resolution or registry type.
+            Resolution results have: secid, weight, url, and optional
+            content_type, parsability ("structured"/"scraped"), schema
+            (SecID reference), parsing_instructions (SecID reference),
+            auth (free-text).
+        message: Guidance text on not_found/error, None otherwise.
+    """
+
+    secid_query: str
+    status: str
+    results: list[dict[str, Any]] = field(default_factory=list)
+    message: str | None = None
+
+    @property
+    def best_url(self) -> str | None:
+        """Highest-weight valid URL from resolution results, or None.
+
+        Only absolute http(s) URLs count (see _validate_url). If the top
+        result carries a hostile or malformed URL, the next valid one is
+        returned instead of None.
+        """
+        resolved = self.resolution_results
+        return resolved[0]["url"] if resolved else None
+
+    @property
+    def was_corrected(self) -> bool:
+        """True if the server corrected the input."""
+        return self.status == "corrected"
+
+    @property
+    def resolution_results(self) -> list[dict[str, Any]]:
+        """Only results with a numeric weight and a valid http(s) url, sorted
+        by weight descending. Entries with a missing, null, or non-numeric
+        weight, or a url that fails _validate_url (javascript:, data:,
+        relative, ...), are left out."""
+        return sorted(
+            [r for r in self.results
+             if isinstance(r, dict) and _is_weight(r.get("weight"))
+             and _validate_url(r.get("url")) is not None],
+            key=lambda r: r["weight"],
+            reverse=True,
+        )
+
+    @property
+    def registry_results(self) -> list[dict[str, Any]]:
+        """Only results with data (registry/browsing info)."""
+        return [r for r in self.results if isinstance(r, dict) and "data" in r]
+
+
+def _is_weight(value: Any) -> bool:
+    """True for a finite int/float. bool is excluded (it is an int subclass)."""
+    return (isinstance(value, (int, float)) and not isinstance(value, bool)
+            and math.isfinite(value))
+
+
+# The resolver response is untrusted (a hostile, federated, or MITM'd resolver
+# is in scope). Only absolute http(s) URLs may be surfaced. The check is done
+# by hand rather than with urlparse so that all three reference clients apply
+# exactly the same rule; parsers disagree on inputs such as "http:evil",
+# "http:///evil" and "http:\\evil" (a WHATWG parser accepts all three).
+ALLOWED_URL_SCHEMES = frozenset({"https", "http"})
+
+
+def _validate_url(url: Any) -> str | None:
+    """Return url only if it is an absolute http(s) URL with a host, else None.
+
+    Rules (identical in the Python, TypeScript and Go clients):
+      1. a non-empty string with no ASCII control characters or spaces;
+      2. begins with "http://" or "https://" (scheme case-insensitive);
+      3. the authority (up to the first "/", "?", "#" or backslash), minus
+         any "userinfo@", is non-empty and does not start with ":".
+    """
+    if not isinstance(url, str) or not url:
+        return None
+    if any(ord(ch) <= 0x20 or ord(ch) == 0x7F for ch in url):
+        return None
+    scheme, sep, rest = url.partition("://")
+    if not sep or scheme.lower() not in ALLOWED_URL_SCHEMES:
+        return None
+    end = len(rest)
+    for delim in "/?#\\":
+        i = rest.find(delim)
+        if i != -1:
+            end = min(end, i)
+    host = rest[:end].rpartition("@")[2]
+    if not host or host.startswith(":"):
+        return None
+    return url
+
+
+def _sanitize_terminal(text: Any) -> str:
+    """Strip C0/C1 control chars (incl. ESC) from server-controlled text before
+    printing to a terminal — prevents ANSI/escape-sequence injection.
+
+    Accepts any value: a hostile resolver can send a number or object where a
+    string is expected, and printing it must not crash the CLI."""
+    if not isinstance(text, str):
+        text = "" if text is None else str(text)
+    return "".join(
+        ch for ch in text
+        if not (ord(ch) < 0x20 or ord(ch) == 0x7F or 0x80 <= ord(ch) <= 0x9F)
+    )
+
+
+_INVALID = object()
+
+# socket.timeout is an alias of TimeoutError from 3.10; on 3.9 it is a
+# separate OSError subclass.
+_TIMEOUTS = (TimeoutError, socket.timeout)
+
+
+def _parse_json(body: bytes) -> Any:
+    """Decode a response body as JSON, returning _INVALID on any failure."""
+    try:
+        return json.loads(body.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError, RecursionError):
+        return _INVALID
+
+
+def _envelope(data: dict[str, Any], secid: str) -> SecIDResponse:
+    """Build a SecIDResponse from an untrusted JSON object, type-checking each
+    field. Wrong-typed fields fall back to defaults; non-object results are
+    dropped so the result helpers never see them."""
+    query = data.get("secid_query")
+    status = data.get("status")
+    message = data.get("message")
+    results = data.get("results")
+    return SecIDResponse(
+        secid_query=query if isinstance(query, str) else secid,
+        status=status if isinstance(status, str) and status else "error",
+        results=[r for r in results if isinstance(r, dict)] if isinstance(results, list) else [],
+        message=message if isinstance(message, str) else None,
+    )
+
+
+class SecIDClient:
+    """HTTP client for the SecID resolve API.
+
+    Args:
+        base_url: API base URL. Defaults to the public SecID service.
+    """
+
+    def __init__(self, base_url: str = DEFAULT_BASE_URL, timeout: int = DEFAULT_TIMEOUT) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def resolve(self, secid: str) -> SecIDResponse:
+        """Resolve a SecID string to URL(s).
+
+        The # character is automatically encoded as %23 in the query parameter.
+
+        Args:
+            secid: Full SecID string, e.g. "secid:advisory/mitre.org/cve#CVE-2021-44228"
+
+        Returns:
+            SecIDResponse with status, results, and optional message. Never
+            raises for network, HTTP, or response-format problems: those come
+            back as status="error" with an explanatory message.
+        """
+        def error(message: str) -> SecIDResponse:
+            return SecIDResponse(secid_query=secid, status="error", message=message)
+
+        try:
+            encoded = urllib.parse.quote(secid, safe="")
+        except UnicodeEncodeError:  # a lone surrogate cannot be UTF-8 encoded
+            return error("SecID is not valid Unicode (unpaired surrogate)")
+        url = f"{self.base_url}/api/v1/resolve?secid={encoded}"
+
+        # Every failure mode becomes status="error"; resolve() never raises.
+        # OSError covers URLError, socket timeouts, and connection resets;
+        # HTTPException covers malformed HTTP (IncompleteRead, BadStatusLine);
+        # ValueError covers an unusable base_url ("unknown url type").
+        try:
+            req = urllib.request.Request(url, headers={
+                "Accept": "application/json",
+                "User-Agent": f"secid-python-client/{__version__}",
+            })
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                body = resp.read(MAX_RESPONSE_BYTES + 1)
+        except urllib.error.HTTPError as e:
+            # Non-2xx: the resolver may still send a JSON envelope.
+            try:
+                body = e.read(MAX_RESPONSE_BYTES + 1)
+            except (OSError, http.client.HTTPException, ValueError) as read_err:
+                return error(f"HTTP {e.code}: error reading body: {read_err}")
+            data = _parse_json(body)
+            if not isinstance(data, dict):
+                text = body[:200].decode("utf-8", errors="replace")
+                return error(f"HTTP {e.code}: {text}")
+            return _envelope(data, secid)
+        except urllib.error.URLError as e:
+            if isinstance(e.reason, _TIMEOUTS):
+                return error(f"Request timeout after {self.timeout}s: {e.reason}")
+            return error(f"Connection error: {e.reason}")
+        except _TIMEOUTS as e:
+            # A timeout while waiting for or reading the response is raised
+            # bare, not wrapped in URLError.
+            return error(f"Request timeout after {self.timeout}s: {e}")
+        except (OSError, http.client.HTTPException) as e:
+            return error(f"Connection error: {e}")
+        except ValueError as e:
+            return error(f"Invalid request URL {url!r}: {e}")
+
+        if len(body) > MAX_RESPONSE_BYTES:
+            return error(f"Response exceeds {MAX_RESPONSE_BYTES} byte limit")
+        data = _parse_json(body)
+        if data is _INVALID:
+            return error("Invalid response (not JSON)")
+        if not isinstance(data, dict):
+            return error(f"Invalid response: expected a JSON object, got {type(data).__name__}")
+        return _envelope(data, secid)
+
+    def best_url(self, secid: str) -> str | None:
+        """Resolve a SecID and return the highest-weight URL, or None."""
+        return self.resolve(secid).best_url
+
+    def lookup(self, type: str, identifier: str) -> SecIDResponse:
+        """Cross-source search: find an identifier across all sources of a type.
+
+        Equivalent to resolve(f"secid:{type}/{identifier}").
+
+        Args:
+            type: SecID type (advisory, weakness, ttp, control, capability, methodology, disclosure, regulation, entity, reference).
+            identifier: The identifier to search for, e.g. "CVE-2021-44228".
+        """
+        return self.resolve(f"secid:{type}/{identifier}")
+
+
+def main() -> None:
+    if len(sys.argv) < 2 or sys.argv[1] in ("-h", "--help"):
+        print("Usage: secid [--json] <secid>")
+        print()
+        print("Examples:")
+        print('  secid "secid:advisory/mitre.org/cve#CVE-2021-44228"')
+        print('  secid --json "secid:advisory/mitre.org/cve#CVE-2021-44228"')
+        print('  secid "secid:advisory/CVE-2021-44228"')
+        sys.exit(0)
+
+    json_mode = "--json" in sys.argv
+    args = [a for a in sys.argv[1:] if a != "--json"]
+    if not args:
+        print("Error: no SecID provided", file=sys.stderr)
+        sys.exit(1)
+
+    client = SecIDClient()
+    response = client.resolve(args[0])
+
+    if json_mode:
+        print(json.dumps({
+            "secid_query": response.secid_query,
+            "status": response.status,
+            "results": response.results,
+            "message": response.message,
+        }, indent=2))
+    elif response.status in ("found", "corrected"):
+        url = response.best_url
+        if url:
+            if response.was_corrected:
+                print(f"(corrected to: {_sanitize_terminal(str(response.results[0].get('secid', '')))})", file=sys.stderr)
+            print(_sanitize_terminal(url))
+        else:
+            for r in response.registry_results:
+                print(json.dumps(r, indent=2))
+    elif response.status == "related":
+        for r in response.results:
+            print(json.dumps(r, indent=2))
+    else:
+        msg = response.message or "No results"
+        print(f"{response.status}: {_sanitize_terminal(msg)}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()