csa-secid 0.1.0__tar.gz

csa_secid-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+dist/
+*.egg-info/
+__pycache__/
+*.pyc
+build/

csa_secid-0.1.0/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.

csa_secid-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: csa-secid
+Version: 0.1.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-0.1.0/README.md

@@ -0,0 +1,95 @@
+# 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-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling>=1.27"]  # PEP 639 license expression support
+build-backend = "hatchling.build"
+
+[project]
+# PyPI has a flat namespace, so the distribution name carries the csa- prefix.
+# The import module (secid_client) and the CLI command (secid) stay simple.
+name = "csa-secid"
+dynamic = ["version"]  # read from __version__ in secid_client.py
+description = "Resolve security identifiers to URLs using the SecID API"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.9"
+authors = [
+    { name = "Cloud Security Alliance", email = "research@cloudsecurityalliance.org" },
+]
+keywords = ["security", "cve", "vulnerability", "secid", "cybersecurity"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+]
+
+[project.scripts]
+secid = "secid_client:main"
+
+[project.urls]
+Homepage = "https://github.com/CloudSecurityAlliance/SecID"
+Repository = "https://github.com/CloudSecurityAlliance/SecID-Client-SDK"
+Documentation = "https://secid.cloudsecurityalliance.org"
+Issues = "https://github.com/CloudSecurityAlliance/SecID-Client-SDK/issues"
+
+[tool.hatch.version]
+path = "secid_client.py"
+
+[tool.hatch.build.targets.wheel]
+only-include = ["secid_client.py"]

csa_secid-0.1.0/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__ = "0.1.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()

csa_secid-0.1.0/test_secid_client.py

@@ -0,0 +1,487 @@
+"""Fixture-driven tests for the Python SecID client.
+
+Reads ../tests/fixtures.json and runs each test case against a local mock server.
+No external dependencies — uses stdlib http.server + pytest (or unittest).
+
+Run: pytest python/test_secid_client.py -v
+"""
+
+import json
+import os
+import threading
+import time
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from pathlib import Path
+
+import pytest
+
+from secid_client import SecIDClient
+
+FIXTURES_PATH = Path(__file__).resolve().parent.parent / "tests" / "fixtures.json"
+
+
+def load_fixtures():
+    with open(FIXTURES_PATH) as f:
+        return json.load(f)["tests"]
+
+
+FIXTURES = load_fixtures()
+
+
+def fixture_ids():
+    return [t["name"] for t in FIXTURES]
+
+
+# ---------------------------------------------------------------------------
+# Mock HTTP server
+# ---------------------------------------------------------------------------
+
+class MockHandler(BaseHTTPRequestHandler):
+    """Serves canned responses from fixture data. Records request URLs."""
+
+    response_body = b"{}"
+    response_status = 200
+    response_content_type = "application/json"
+    recorded_urls = []
+    hang = False
+    oversized_bytes = 0
+
+    def do_GET(self):
+        MockHandler.recorded_urls.append(self.path)
+
+        if MockHandler.hang:
+            # Sleep long enough that the client should time out
+            time.sleep(10)
+            return
+
+        if MockHandler.oversized_bytes > 0:
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.end_headers()
+            self.wfile.write(b"x" * MockHandler.oversized_bytes)
+            return
+
+        self.send_response(MockHandler.response_status)
+        self.send_header("Content-Type", MockHandler.response_content_type)
+        self.end_headers()
+        self.wfile.write(MockHandler.response_body)
+
+    def log_message(self, format, *args):
+        pass  # Suppress request logging
+
+
+def start_mock_server():
+    server = HTTPServer(("127.0.0.1", 0), MockHandler)
+    port = server.server_address[1]
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    return server, port
+
+
+def configure_mock(mock_response):
+    """Configure MockHandler class vars from fixture mock_response."""
+    MockHandler.recorded_urls = []
+    MockHandler.hang = False
+    MockHandler.oversized_bytes = 0
+    MockHandler.response_status = 200
+    MockHandler.response_content_type = "application/json"
+    MockHandler.response_body = b"{}"
+
+    behavior = mock_response.get("behavior")
+    if behavior == "timeout":
+        MockHandler.hang = True
+        return
+    if behavior == "oversized_body":
+        MockHandler.oversized_bytes = mock_response["body_size_bytes"]
+        return
+    if behavior == "connection_refused":
+        return  # Handled specially in the test
+
+    if "raw_body" in mock_response:
+        MockHandler.response_body = mock_response["raw_body"].encode()
+        MockHandler.response_content_type = mock_response.get("content_type", "text/html")
+    elif "body" in mock_response:
+        MockHandler.response_body = json.dumps(mock_response["body"]).encode()
+
+    MockHandler.response_status = mock_response.get("http_status", 200)
+
+
+# ---------------------------------------------------------------------------
+# Server fixture (shared across the module)
+# ---------------------------------------------------------------------------
+
+_server = None
+_port = None
+
+
+@pytest.fixture(scope="module")
+def mock_server():
+    global _server, _port
+    if _server is None:
+        _server, _port = start_mock_server()
+    yield _port
+    _server.shutdown()
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+def standard_tests():
+    """Return fixture entries that use a normal mock server (not connection_refused)."""
+    return [t for t in FIXTURES if t["mock_response"].get("behavior") != "connection_refused"]
+
+
+def connection_refused_tests():
+    """Return fixture entries that need no server (connection refused)."""
+    return [t for t in FIXTURES if t["mock_response"].get("behavior") == "connection_refused"]
+
+
+def _invoke_response(client: SecIDClient, inp: dict):
+    method = inp.get("method", "resolve")
+    if method == "lookup":
+        args = inp["args"]
+        return client.lookup(args["type"], args["identifier"])
+    if method == "resolve":
+        return client.resolve(inp["secid"])
+    raise ValueError(f"Unsupported fixture method: {method}")
+
+
+def _assert_request_url(expected: dict):
+    if "request_url_contains" in expected:
+        assert len(MockHandler.recorded_urls) > 0, "No request recorded"
+        url = MockHandler.recorded_urls[-1]
+        assert expected["request_url_contains"] in url, (
+            f"Request URL should contain '{expected['request_url_contains']}', got: {url}"
+        )
+
+    if "request_url_not_contains" in expected:
+        assert len(MockHandler.recorded_urls) > 0, "No request recorded"
+        url = MockHandler.recorded_urls[-1]
+        assert expected["request_url_not_contains"] not in url, (
+            f"Request URL should NOT contain '{expected['request_url_not_contains']}', got: {url}"
+        )
+
+
+@pytest.mark.parametrize(
+    "fixture",
+    standard_tests(),
+    ids=[t["name"] for t in standard_tests()],
+)
+def test_fixture(fixture, mock_server):
+    port = mock_server
+    configure_mock(fixture["mock_response"])
+    expected = fixture["expected"]
+    inp = fixture["input"]
+
+    # Use short timeout for timeout tests
+    is_timeout = fixture["mock_response"].get("behavior") == "timeout"
+    timeout = 2 if is_timeout else 10
+
+    client = SecIDClient(base_url=f"http://127.0.0.1:{port}", timeout=timeout)
+
+    if inp.get("method") == "best_url":
+        url = client.best_url(inp["secid"])
+        if expected.get("raises_error"):
+            assert url is None, f"best_url: expected None on error, got {url}"
+            return
+        assert url == expected.get("best_url"), (
+            f"best_url: expected {expected.get('best_url')}, got {url}"
+        )
+        _assert_request_url(expected)
+        return
+
+    if expected.get("raises_error"):
+        # The Python client never raises: every failure is status="error".
+        resp = _invoke_response(client, inp)
+        assert resp.status == "error", f"Expected error status, got status={resp.status}"
+        if "error_contains" in expected:
+            assert resp.message and expected["error_contains"].lower() in resp.message.lower(), (
+                f"Expected '{expected['error_contains']}' in message: {resp.message}"
+            )
+        return
+
+    # Normal test: call resolve/lookup and check expected fields
+    resp = _invoke_response(client, inp)
+
+    if "status" in expected:
+        assert resp.status == expected["status"], (
+            f"status: expected {expected['status']}, got {resp.status}"
+        )
+
+    if "best_url" in expected:
+        if expected["best_url"] is None:
+            assert resp.best_url is None, f"best_url: expected None, got {resp.best_url}"
+        else:
+            assert resp.best_url == expected["best_url"], (
+                f"best_url: expected {expected['best_url']}, got {resp.best_url}"
+            )
+
+    if "was_corrected" in expected:
+        assert resp.was_corrected == expected["was_corrected"], (
+            f"was_corrected: expected {expected['was_corrected']}, got {resp.was_corrected}"
+        )
+
+    if "resolution_result_count" in expected:
+        actual = len(resp.resolution_results)
+        assert actual == expected["resolution_result_count"], (
+            f"resolution_result_count: expected {expected['resolution_result_count']}, got {actual}"
+        )
+
+    if "registry_result_count" in expected:
+        actual = len(resp.registry_results)
+        assert actual == expected["registry_result_count"], (
+            f"registry_result_count: expected {expected['registry_result_count']}, got {actual}"
+        )
+
+    if "message" in expected:
+        if expected["message"] is None:
+            assert resp.message is None, f"message: expected None, got {resp.message}"
+        else:
+            assert resp.message == expected["message"], (
+                f"message: expected {expected['message']}, got {resp.message}"
+            )
+
+    if "first_resolution_result" in expected:
+        assert len(resp.resolution_results) > 0, "Expected at least one resolution result"
+        first = resp.resolution_results[0]
+        for field_name, want in expected["first_resolution_result"].items():
+            actual = first.get(field_name)
+            assert actual == want, (
+                f"first_resolution_result.{field_name}: expected {want!r}, got {actual!r}"
+            )
+
+    # Encoding assertions: check the URL the client actually sent
+    _assert_request_url(expected)
+
+
+@pytest.mark.parametrize(
+    "fixture",
+    connection_refused_tests(),
+    ids=[t["name"] for t in connection_refused_tests()],
+)
+def test_connection_refused(fixture):
+    # Point client at a port where nothing is listening
+    client = SecIDClient(base_url="http://127.0.0.1:1", timeout=2)
+    inp = fixture["input"]
+    if inp.get("method") == "best_url":
+        assert client.best_url(inp["secid"]) is None
+        return
+    resp = _invoke_response(client, inp)
+    assert resp.status == "error"
+
+
+# ── Untrusted-response hardening (audit findings F-08, F-10-02) ──
+
+from secid_client import SecIDResponse, _validate_url, _sanitize_terminal  # noqa: E402
+
+
+def test_validate_url_scheme_allowlist():
+    assert _validate_url("https://www.cve.org/CVERecord?id=CVE-2021-44228")
+    assert _validate_url("http://example.com/x")
+    for bad in ("javascript:alert(1)", "data:text/html,x", "file:///etc/passwd",
+                "vbscript:msgbox(1)", "//evil.example/x", "/relative", "", None):
+        assert _validate_url(bad) is None, f"{bad!r} must be rejected"
+
+
+def test_best_url_rejects_hostile_scheme():
+    # A hostile resolver returns a javascript: URL as the highest-weight result.
+    r = SecIDResponse(secid_query="x", status="found",
+                      results=[{"weight": 100, "url": "javascript:fetch('//evil')"}])
+    assert r.best_url is None
+    # A valid https result is returned unchanged.
+    r2 = SecIDResponse(secid_query="x", status="found",
+                       results=[{"weight": 100, "url": "https://example.com/ok"}])
+    assert r2.best_url == "https://example.com/ok"
+
+
+def test_sanitize_terminal_strips_control_chars():
+    assert _sanitize_terminal("https://x/\x1b[2Jfake") == "https://x/[2Jfake"
+    assert _sanitize_terminal("plain text") == "plain text"
+
+
+def test_sanitize_terminal_accepts_non_strings():
+    assert _sanitize_terminal(123) == "123"
+    assert _sanitize_terminal(None) == ""
+    assert isinstance(_sanitize_terminal({"a": 1}), str)
+
+
+# ── Hostile resolver responses (audit finding H2) ──
+#
+# The resolver is untrusted. None of these may raise; each must come back as
+# a SecIDResponse whose helpers work.
+
+import socketserver  # noqa: E402
+
+
+class _RawHandler(BaseHTTPRequestHandler):
+    status = 200
+    body = b""
+    delay = 0.0
+    truncate = False
+
+    def do_GET(self):
+        if _RawHandler.delay:
+            # Send headers promptly, then stall mid-body: a read timeout,
+            # not a connect timeout.
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", "100")
+            self.end_headers()
+            self.wfile.write(b'{"status":')
+            self.wfile.flush()
+            time.sleep(_RawHandler.delay)
+            return
+        self.send_response(_RawHandler.status)
+        self.send_header("Content-Type", "application/json")
+        if _RawHandler.truncate:
+            self.send_header("Content-Length", str(len(_RawHandler.body) + 50))
+        self.end_headers()
+        self.wfile.write(_RawHandler.body)
+
+    def log_message(self, format, *args):
+        pass
+
+
+class _ThreadedServer(socketserver.ThreadingMixIn, HTTPServer):
+    daemon_threads = True
+
+
+@pytest.fixture(scope="module")
+def raw_server():
+    server = _ThreadedServer(("127.0.0.1", 0), _RawHandler)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    yield f"http://127.0.0.1:{server.server_address[1]}"
+    server.shutdown()
+
+
+def _serve(body, status=200, delay=0.0, truncate=False):
+    _RawHandler.body = body if isinstance(body, bytes) else json.dumps(body).encode()
+    _RawHandler.status = status
+    _RawHandler.delay = delay
+    _RawHandler.truncate = truncate
+
+
+def _exercise(resp):
+    """Touch every helper; none may raise on a hostile response."""
+    resp.best_url, resp.was_corrected, resp.resolution_results, resp.registry_results
+    return resp
+
+
+@pytest.mark.parametrize("body", [
+    b"null", b"[]", b"42", b'"found"', b"true", b"", b"   ",
+], ids=["null", "array", "number", "string", "bool", "empty", "whitespace"])
+def test_non_object_body_is_error(raw_server, body):
+    _serve(body)
+    resp = _exercise(SecIDClient(raw_server, timeout=5).resolve("secid:x/y/z"))
+    assert resp.status == "error"
+    assert resp.results == []
+
+
+def test_wrongly_typed_envelope_fields(raw_server):
+    _serve({"secid_query": 7, "status": ["found"], "results": {"a": 1}, "message": 5})
+    resp = _exercise(SecIDClient(raw_server, timeout=5).resolve("secid:x/y/z"))
+    assert resp.secid_query == "secid:x/y/z"
+    assert resp.status == "error"
+    assert resp.results == []
+    assert resp.message is None
+
+
+def test_non_dict_results_and_mixed_weights(raw_server):
+    _serve({"status": "found", "results": [
+        17, "junk", None, [1, 2],
+        {"secid": "a", "weight": None, "url": "https://a.example/"},
+        {"secid": "b", "weight": "90", "url": "https://b.example/"},
+        {"secid": "c", "weight": True, "url": "https://c.example/"},
+        {"secid": "d", "weight": 87.5, "url": "https://d.example/"},
+        {"secid": "e", "weight": 90, "url": "https://e.example/"},
+        {"secid": "f", "weight": 99, "url": 12345},
+        {"secid": "g", "data": {"k": "v"}},
+    ]})
+    resp = _exercise(SecIDClient(raw_server, timeout=5).resolve("secid:x/y/z"))
+    assert resp.status == "found"
+    assert len(resp.results) == 7  # the four non-objects are dropped
+    assert [r["secid"] for r in resp.resolution_results] == ["e", "d"]
+    assert resp.best_url == "https://e.example/"
+    assert len(resp.registry_results) == 1
+
+
+def test_non_utf8_body(raw_server):
+    _serve(b"\xff\xfe\xfa not utf-8")
+    assert SecIDClient(raw_server, timeout=5).resolve("secid:x/y/z").status == "error"
+
+
+def test_non_utf8_error_body(raw_server):
+    _serve(b"\xff\xfe\xfa not utf-8", status=502)
+    resp = SecIDClient(raw_server, timeout=5).resolve("secid:x/y/z")
+    assert resp.status == "error"
+    assert resp.message.startswith("HTTP 502")
+
+
+def test_error_status_with_null_json_body(raw_server):
+    _serve(b"null", status=500)
+    resp = SecIDClient(raw_server, timeout=5).resolve("secid:x/y/z")
+    assert resp.status == "error"
+    assert resp.message.startswith("HTTP 500")
+
+
+def test_truncated_body(raw_server):
+    _serve(b'{"status": "fo', truncate=True)
+    assert SecIDClient(raw_server, timeout=5).resolve("secid:x/y/z").status == "error"
+
+
+def test_read_timeout_mid_body(raw_server):
+    _serve(b"", delay=3)
+    resp = SecIDClient(raw_server, timeout=1).resolve("secid:x/y/z")
+    assert resp.status == "error"
+    assert "timeout" in resp.message.lower()
+
+
+def test_deeply_nested_json(raw_server):
+    _serve(b"[" * 100000 + b"]" * 100000)
+    assert SecIDClient(raw_server, timeout=5).resolve("secid:x/y/z").status == "error"
+
+
+@pytest.mark.parametrize("base_url", ["not a url", "ftp://example.com", ""])
+def test_unusable_base_url(base_url):
+    resp = SecIDClient(base_url, timeout=2).resolve("secid:x/y/z")
+    assert resp.status == "error"
+
+
+def test_cli_survives_hostile_values(monkeypatch, capsys):
+    import secid_client
+
+    hostile = SecIDResponse(secid_query="q", status="corrected", results=[
+        {"secid": 42, "weight": 100, "url": "https://ok.example/"},
+    ])
+    monkeypatch.setattr(secid_client.SecIDClient, "resolve", lambda self, s: hostile)
+    monkeypatch.setattr(secid_client.sys, "argv", ["secid", "secid:x/y/z"])
+    secid_client.main()
+    out = capsys.readouterr()
+    assert out.out.strip() == "https://ok.example/"
+    assert "corrected to: 42" in out.err
+
+
+def test_unpaired_surrogate_secid():
+    resp = SecIDClient("http://127.0.0.1:1", timeout=2).resolve("secid:x/y/\ud800")
+    assert resp.status == "error"
+    assert "Unicode" in resp.message
+
+
+def test_user_agent_carries_version(mock_server):
+    import secid_client
+
+    configure_mock({"http_status": 200, "body": {"status": "found", "results": []}})
+    captured = {}
+    orig = MockHandler.do_GET
+
+    def spy(self):
+        captured["ua"] = self.headers.get("User-Agent")
+        orig(self)
+
+    MockHandler.do_GET = spy
+    try:
+        SecIDClient(base_url=f"http://127.0.0.1:{mock_server}", timeout=5).resolve("secid:x/y/z")
+    finally:
+        MockHandler.do_GET = orig
+    assert captured["ua"] == f"secid-python-client/{secid_client.__version__}"