ghsa-client 0.1.0__tar.gz

ghsa_client-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

ghsa_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Efi Weiss
+
+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.

ghsa_client-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: ghsa-client
+Version: 0.1.0
+Summary: A Python client library for the GitHub Security Advisory (GHSA) API
+Project-URL: Homepage, https://github.com/auto-exploit/ghsa-client
+Project-URL: Documentation, https://ghsa-client.readthedocs.io/
+Project-URL: Repository, https://github.com/auto-exploit/ghsa-client.git
+Project-URL: Issues, https://github.com/auto-exploit/ghsa-client/issues
+Project-URL: Changelog, https://github.com/auto-exploit/ghsa-client/blob/main/CHANGELOG.md
+License: MIT
+License-File: LICENSE
+Keywords: advisory,cve,ghsa,github,security,vulnerability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: black>=22.0.0; extra == 'dev'
+Requires-Dist: isort>=5.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.4.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# GHSA Client
+
+A Python client library for the GitHub Security Advisory (GHSA) API, providing structured access to security advisory data.
+
+## Features
+
+- **Type-safe models**: Full Pydantic models for GHSA data structures
+- **Rate limiting**: Built-in rate limit handling and retry logic
+- **Flexible queries**: Search advisories with various filters
+- **Comprehensive data**: Access to all GHSA fields including CVSS scores, CWE mappings, and package information
+
+## Installation
+
+```bash
+pip install ghsa-client
+```
+
+## Quick Start
+
+```python
+import logging
+from ghsa_client import GHSAClient, GHSA_ID
+
+# Set up logging
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+# Create client
+client = GHSAClient(logger)
+
+# Get a specific advisory
+ghsa_id = GHSA_ID("GHSA-gq96-8w38-hhj2")
+advisory = client.get_advisory(ghsa_id)
+
+print(f"Advisory: {advisory.summary}")
+print(f"Severity: {advisory.severity}")
+print(f"CVSS Score: {advisory.cvss.score if advisory.cvss else 'N/A'}")
+```
+
+## Usage
+
+### Authentication
+
+The client automatically uses the `GITHUB_TOKEN` environment variable if available:
+
+```bash
+export GITHUB_TOKEN=your_github_token_here
+```
+
+### Getting an Advisory
+
+```python
+from ghsa_client import GHSAClient, GHSA_ID
+
+client = GHSAClient(logger)
+advisory = client.get_advisory(GHSA_ID("GHSA-gq96-8w38-hhj2"))
+
+# Access advisory properties
+print(advisory.summary)
+print(advisory.severity)
+print(advisory.published_at)
+print(advisory.vulnerabilities)
+```
+
+### Searching Advisories
+
+```python
+# Search by ecosystem
+advisories = client.search_advisories(ecosystem="npm")
+
+# Search by severity
+advisories = client.search_advisories(severity="high")
+
+# Search by date range
+advisories = client.search_advisories(published="2024-01-01..2024-12-31")
+
+# Get all advisories for a year
+advisories = client.get_all_advisories_for_year(2024)
+```
+
+### Rate Limiting
+
+The client automatically handles GitHub's rate limits:
+
+```python
+# Check remaining rate limit
+rate_limit = client.get_ratelimit_remaining()
+print(f"Remaining requests: {rate_limit['resources']['core']['remaining']}")
+
+# The client will automatically wait for rate limit reset when needed
+```
+
+## Models
+
+### Advisory
+
+The main model representing a GitHub Security Advisory:
+
+```python
+from ghsa_client import Advisory
+
+advisory: Advisory = client.get_advisory(ghsa_id)
+
+# Core properties
+advisory.ghsa_id          # GHSA_ID object
+advisory.cve_id           # Optional CVE_ID object
+advisory.summary          # str
+advisory.severity         # str
+advisory.published_at     # str (ISO date)
+advisory.description      # Optional[str]
+
+# Vulnerability data
+advisory.vulnerabilities  # List[Vulnerability]
+advisory.affected_packages # List[Package] (computed property)
+
+# CVSS data
+advisory.cvss             # Optional[CVSS]
+advisory.cwes             # Optional[List[str]]
+
+# Repository information
+advisory.source_code_location # Optional[str]
+advisory.repository_url   # str (property, raises if not found)
+
+# References
+advisory.references       # List[str]
+```
+
+### GHSA_ID
+
+Type-safe GHSA identifier with validation:
+
+```python
+from ghsa_client import GHSA_ID, InvalidGHSAIDError
+
+try:
+    ghsa_id = GHSA_ID("GHSA-gq96-8w38-hhj2")
+    print(ghsa_id.id)  # "GHSA-gq96-8w38-hhj2"
+except InvalidGHSAIDError as e:
+    print(f"Invalid GHSA ID: {e}")
+```
+
+### CVE_ID
+
+Type-safe CVE identifier with validation:
+
+```python
+from ghsa_client import CVE_ID
+
+cve_id = CVE_ID("CVE-2024-12345")
+print(cve_id.id)  # "CVE-2024-12345"
+```
+
+
+## Error Handling
+
+The client raises specific exceptions for different error conditions:
+
+```python
+from ghsa_client import RateLimitExceeded, GHSAClient
+import requests
+
+try:
+    advisory = client.get_advisory(ghsa_id)
+except requests.HTTPError as e:
+    if e.response.status_code == 404:
+        print("Advisory not found")
+    else:
+        print(f"HTTP error: {e}")
+except RateLimitExceeded as e:
+    print(f"Rate limit exceeded: {e}")
+except requests.RequestException as e:
+    print(f"Network error: {e}")
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/auto-exploit/ghsa-client.git
+cd ghsa-client
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Code Formatting
+
+```bash
+black .
+isort .
+```
+
+### Type Checking
+
+```bash
+mypy src/ghsa_client
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a history of changes.

ghsa_client-0.1.0/README.md

@@ -0,0 +1,214 @@
+# GHSA Client
+
+A Python client library for the GitHub Security Advisory (GHSA) API, providing structured access to security advisory data.
+
+## Features
+
+- **Type-safe models**: Full Pydantic models for GHSA data structures
+- **Rate limiting**: Built-in rate limit handling and retry logic
+- **Flexible queries**: Search advisories with various filters
+- **Comprehensive data**: Access to all GHSA fields including CVSS scores, CWE mappings, and package information
+
+## Installation
+
+```bash
+pip install ghsa-client
+```
+
+## Quick Start
+
+```python
+import logging
+from ghsa_client import GHSAClient, GHSA_ID
+
+# Set up logging
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+
+# Create client
+client = GHSAClient(logger)
+
+# Get a specific advisory
+ghsa_id = GHSA_ID("GHSA-gq96-8w38-hhj2")
+advisory = client.get_advisory(ghsa_id)
+
+print(f"Advisory: {advisory.summary}")
+print(f"Severity: {advisory.severity}")
+print(f"CVSS Score: {advisory.cvss.score if advisory.cvss else 'N/A'}")
+```
+
+## Usage
+
+### Authentication
+
+The client automatically uses the `GITHUB_TOKEN` environment variable if available:
+
+```bash
+export GITHUB_TOKEN=your_github_token_here
+```
+
+### Getting an Advisory
+
+```python
+from ghsa_client import GHSAClient, GHSA_ID
+
+client = GHSAClient(logger)
+advisory = client.get_advisory(GHSA_ID("GHSA-gq96-8w38-hhj2"))
+
+# Access advisory properties
+print(advisory.summary)
+print(advisory.severity)
+print(advisory.published_at)
+print(advisory.vulnerabilities)
+```
+
+### Searching Advisories
+
+```python
+# Search by ecosystem
+advisories = client.search_advisories(ecosystem="npm")
+
+# Search by severity
+advisories = client.search_advisories(severity="high")
+
+# Search by date range
+advisories = client.search_advisories(published="2024-01-01..2024-12-31")
+
+# Get all advisories for a year
+advisories = client.get_all_advisories_for_year(2024)
+```
+
+### Rate Limiting
+
+The client automatically handles GitHub's rate limits:
+
+```python
+# Check remaining rate limit
+rate_limit = client.get_ratelimit_remaining()
+print(f"Remaining requests: {rate_limit['resources']['core']['remaining']}")
+
+# The client will automatically wait for rate limit reset when needed
+```
+
+## Models
+
+### Advisory
+
+The main model representing a GitHub Security Advisory:
+
+```python
+from ghsa_client import Advisory
+
+advisory: Advisory = client.get_advisory(ghsa_id)
+
+# Core properties
+advisory.ghsa_id          # GHSA_ID object
+advisory.cve_id           # Optional CVE_ID object
+advisory.summary          # str
+advisory.severity         # str
+advisory.published_at     # str (ISO date)
+advisory.description      # Optional[str]
+
+# Vulnerability data
+advisory.vulnerabilities  # List[Vulnerability]
+advisory.affected_packages # List[Package] (computed property)
+
+# CVSS data
+advisory.cvss             # Optional[CVSS]
+advisory.cwes             # Optional[List[str]]
+
+# Repository information
+advisory.source_code_location # Optional[str]
+advisory.repository_url   # str (property, raises if not found)
+
+# References
+advisory.references       # List[str]
+```
+
+### GHSA_ID
+
+Type-safe GHSA identifier with validation:
+
+```python
+from ghsa_client import GHSA_ID, InvalidGHSAIDError
+
+try:
+    ghsa_id = GHSA_ID("GHSA-gq96-8w38-hhj2")
+    print(ghsa_id.id)  # "GHSA-gq96-8w38-hhj2"
+except InvalidGHSAIDError as e:
+    print(f"Invalid GHSA ID: {e}")
+```
+
+### CVE_ID
+
+Type-safe CVE identifier with validation:
+
+```python
+from ghsa_client import CVE_ID
+
+cve_id = CVE_ID("CVE-2024-12345")
+print(cve_id.id)  # "CVE-2024-12345"
+```
+
+
+## Error Handling
+
+The client raises specific exceptions for different error conditions:
+
+```python
+from ghsa_client import RateLimitExceeded, GHSAClient
+import requests
+
+try:
+    advisory = client.get_advisory(ghsa_id)
+except requests.HTTPError as e:
+    if e.response.status_code == 404:
+        print("Advisory not found")
+    else:
+        print(f"HTTP error: {e}")
+except RateLimitExceeded as e:
+    print(f"Rate limit exceeded: {e}")
+except requests.RequestException as e:
+    print(f"Network error: {e}")
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/auto-exploit/ghsa-client.git
+cd ghsa-client
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Code Formatting
+
+```bash
+black .
+isort .
+```
+
+### Type Checking
+
+```bash
+mypy src/ghsa_client
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a history of changes.

ghsa_client-0.1.0/pyproject.toml

@@ -0,0 +1,134 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ghsa-client"
+version = "0.1.0"
+description = "A Python client library for the GitHub Security Advisory (GHSA) API"
+readme = "README.md"
+license = {text = "MIT"}
+keywords = ["security", "advisory", "github", "ghsa", "vulnerability", "cve"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "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",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "pydantic>=2.0.0",
+    "requests>=2.25.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "black>=22.0.0",
+    "isort>=5.0.0",
+    "mypy>=1.0.0",
+    "ruff>=0.1.0",
+]
+docs = [
+    "mkdocs>=1.4.0",
+    "mkdocs-material>=9.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/auto-exploit/ghsa-client"
+Documentation = "https://ghsa-client.readthedocs.io/"
+Repository = "https://github.com/auto-exploit/ghsa-client.git"
+Issues = "https://github.com/auto-exploit/ghsa-client/issues"
+Changelog = "https://github.com/auto-exploit/ghsa-client/blob/main/CHANGELOG.md"
+
+[project.scripts]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ghsa_client"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/README.md",
+    "/pyproject.toml",
+]
+
+[tool.black]
+line-length = 88
+target-version = ['py39']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # directories
+  \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | build
+  | dist
+)/
+'''
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+line_length = 88
+known_first_party = ["ghsa_client"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 88
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "UP", # pyupgrade
+]
+ignore = [
+    "E501",  # line too long, handled by black
+    "B008",  # do not perform function calls in argument defaults
+    "C901",  # too complex
+]
+
+[tool.ruff.per-file-ignores]
+"__init__.py" = ["F401"]

ghsa_client-0.1.0/src/ghsa_client/__init__.py

@@ -0,0 +1,19 @@
+"""GitHub Security Advisory (GHSA) client library.
+
+A Python library for interacting with the GitHub Security Advisory API,
+providing structured access to security advisory data.
+
+Main exports:
+- GHSAClient: Main client for interacting with the GHSA API
+- Advisory: Main model representing a GitHub Security Advisory
+- GHSA_ID: Type-safe GHSA identifier with validation
+- CVE_ID: Type-safe CVE identifier with validation
+- RateLimitExceeded: Exception raised when API rate limit is exceeded
+"""
+
+from .client import GHSAClient
+from .models import Advisory, GHSA_ID, CVE_ID
+from .exceptions import RateLimitExceeded
+
+__version__ = "0.1.0"
+__all__ = ["GHSAClient", "Advisory", "GHSA_ID", "CVE_ID", "RateLimitExceeded"]

ghsa_client-0.1.0/src/ghsa_client/client.py

@@ -0,0 +1,140 @@
+"""GitHub Security Advisory (GHSA) API client."""
+
+import os
+import requests
+import logging
+from time import sleep, time
+from typing import Any, Optional, cast
+from .exceptions import RateLimitExceeded
+from .models import Advisory, GHSA_ID
+
+
+class GHSAClient:
+    """Client for querying GitHub Security Advisory database via REST API."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        blocking_rate_limit: bool = True,
+        logger: logging.Logger = logging.getLogger(__name__), 
+        base_url: str = "https://api.github.com",
+    ) -> None:
+        """Initialize the GHSA client.
+        
+        Args:
+            api_key: Optional GitHub API key. If provided, enables much higher rate limits
+                (5000 requests/hour vs 60 requests/hour for unauthenticated requests).
+                Falls back to GITHUB_TOKEN environment variable if not provided.
+            blocking_rate_limit: If True, automatically waits for rate limit reset before
+                making requests. If False, raises RateLimitExceeded when rate limited.
+            logger: Logger instance for debug and error messages.
+            base_url: Base URL for GitHub API. Defaults to production API.
+        """
+        self.base_url = base_url
+        self.session = requests.Session()
+        self.logger = logger
+        self.blocking_rate_limit = blocking_rate_limit
+        # Set up headers
+        headers = {
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        elif GITHUB_TOKEN := os.getenv("GITHUB_TOKEN"):
+            headers["Authorization"] = f"Bearer {GITHUB_TOKEN}"
+
+        self.session.headers.update(headers)
+
+    def _get_with_rate_limit_retry(
+        self, url: str, *args: Any, **kwargs: Any
+    ) -> requests.Response:
+        for _ in range(3):
+            try:
+                if self.blocking_rate_limit:
+                    self.wait_for_ratelimit()
+                response = self.session.get(url, *args, **kwargs)
+                response.raise_for_status()
+                return response
+            except requests.HTTPError as e:
+                if e.response.status_code == 403 and e.response.text.startswith(
+                    "rate limit exceeded"
+                ):
+                    sleep(1)
+                    continue
+                raise e
+
+        raise RateLimitExceeded(f"Rate limit exceeded for advisory")
+
+    def get_advisory(self, ghsa_id: GHSA_ID) -> Advisory:
+        url = f"{self.base_url}/advisories/{ghsa_id}"
+        self.logger.debug(f"Requesting advisory from URL: {url}")
+
+        try:
+            response = self._get_with_rate_limit_retry(url)
+            return Advisory.model_validate(response.json())
+        except requests.HTTPError as e:
+            if e.response.status_code == 404:
+                self.logger.exception(f"Advisory {ghsa_id} not found")
+            else:
+                self.logger.exception(f"HTTP error retrieving advisory {ghsa_id}: {e}")
+            raise
+        except requests.RequestException:
+            self.logger.exception(f"Network error retrieving advisory {ghsa_id}")
+            raise
+
+    def search_advisories(self, **filters: Any) -> list[Advisory]:
+        """
+        Search for advisories with optional filters.
+
+        Args:
+            **filters: Keyword arguments for filtering (ecosystem, severity, etc.)
+
+        Returns:
+            List[Advisory]: List of matching advisories as structured dataclasses
+        """
+        url = f"{self.base_url}/advisories"
+        self.logger.debug(f"Searching advisories with filters: {filters}")
+
+        try:
+            response = self._get_with_rate_limit_retry(url, params=filters)
+            raw_advisories = response.json()
+            advisories = [Advisory.model_validate(data) for data in raw_advisories]
+
+            self.logger.info(f"Found {len(advisories)} advisories matching filters")
+
+            return advisories
+
+        except requests.RequestException:
+            self.logger.exception("Error searching advisories")
+            raise
+
+    def get_all_advisories_for_year(self, year: int) -> list[Advisory]:
+        """
+        Returns a list of GHSA_IDs for all vulnerabilities published in a given year.
+        """
+        return self.search_advisories(published=f"{year}-01-01..{year}-12-31")
+
+    def get_ratelimit_remaining(self) -> dict[str, Any]:
+        """
+        Returns the number of requests remaining in the current rate limit window.
+        """
+        response = self.session.get(f"{self.base_url}/rate_limit")
+        response.raise_for_status()
+        return cast(dict[str, Any], response.json())
+
+    def wait_for_ratelimit(self) -> None:
+        """
+        Waits for the rate limit to reset.
+        """
+        ratelimit_remaining = self.get_ratelimit_remaining()
+        if ratelimit_remaining["resources"]["core"]["remaining"] > 0:
+            return
+        reset_timestamp = ratelimit_remaining["resources"]["core"]["reset"]
+        self.logger.info(f"Rate limit reset in {reset_timestamp - time()} seconds")
+        sleep(reset_timestamp - time())
+        ratelimit_remaining = self.get_ratelimit_remaining()
+        if ratelimit_remaining["resources"]["core"]["remaining"] == 0:
+            raise RateLimitExceeded(f"Rate limit not reset")

ghsa_client-0.1.0/src/ghsa_client/exceptions/__init__.py

@@ -0,0 +1,5 @@
+"""Exceptions specific to GHSA operations."""
+
+from .rate_limit import RateLimitExceeded
+
+__all__ = ["RateLimitExceeded"]

ghsa_client-0.1.0/src/ghsa_client/exceptions/rate_limit.py

@@ -0,0 +1,7 @@
+"""Rate limit exception for GHSA API operations."""
+
+
+class RateLimitExceeded(Exception):
+    """Raised when API rate limit is exceeded."""
+
+    pass

ghsa_client-0.1.0/src/ghsa_client/models/__init__.py

@@ -0,0 +1,19 @@
+"""Models for GHSA operations."""
+
+from .ghsa_id import GHSA_ID, InvalidGHSAIDError
+from .advisory import Advisory, NoSourceCodeLocationFound
+from .base import CVE_ID, CVSS, CVSSVector, Package, Vulnerability, GitCommit, VersionPredicate
+
+__all__ = [
+    "GHSA_ID", 
+    "InvalidGHSAIDError",
+    "Advisory", 
+    "NoSourceCodeLocationFound",
+    "CVE_ID",
+    "CVSS", 
+    "CVSSVector",
+    "Package",
+    "Vulnerability",
+    "GitCommit",
+    "VersionPredicate",
+]

ghsa_client-0.1.0/src/ghsa_client/models/advisory.py

@@ -0,0 +1,161 @@
+"""Advisory model for GHSA operations."""
+
+from typing import Optional, Any
+from pydantic import BaseModel, field_validator, computed_field, model_validator
+
+from .ghsa_id import GHSA_ID
+from .base import CVE_ID, Vulnerability, CVSS, Package, GitCommit
+
+
+class NoSourceCodeLocationFound(Exception):
+    """Raised when source code location is not found in advisory."""
+    pass
+
+
+class Advisory(BaseModel):
+    """Represents a GitHub Security Advisory (GHSA)."""
+
+    ghsa_id: GHSA_ID
+    cve_id: Optional[CVE_ID] = None
+    summary: str
+    severity: str
+    published_at: str
+    vulnerabilities: list[Vulnerability]
+    description: Optional[str] = None
+    source_code_location: Optional[str] = None
+    cwes: Optional[list[str]] = None
+    references: list[str] = []
+    cvss: Optional[CVSS] = None
+    last_vulnerable_version: Optional[str] = None
+
+    # Git commit information (populated by GitRepoHelper)
+    last_vulnerable_commit: Optional[GitCommit] = None
+    first_patched_commit: Optional[GitCommit] = None
+
+    @field_validator("ghsa_id", mode="before")
+    @classmethod
+    def validate_ghsa_id(cls, v: Any) -> GHSA_ID:
+        if isinstance(v, str):
+            return GHSA_ID(id=v)
+        if isinstance(v, GHSA_ID):
+            return v
+        if isinstance(v, dict):
+            return GHSA_ID.model_validate(v)
+        raise ValueError("Invalid value for ghsa_id")
+
+    @field_validator("cve_id", mode="before")
+    @classmethod
+    def validate_cve_id(cls, v: Any) -> Optional[CVE_ID]:
+        if v is None:
+            return None
+        if isinstance(v, str):
+            return CVE_ID(id=v)
+        if isinstance(v, CVE_ID):
+            return v
+        if isinstance(v, dict):
+            return CVE_ID.model_validate(v)
+        raise ValueError("Invalid value for cve_id")
+
+    @field_validator("cwes", mode="before")
+    @classmethod
+    def parse_cwes(cls, v: Any) -> Optional[list[str]]:
+        if not v:
+            return None
+        cwes = []
+        for cwe_data in v:
+            if isinstance(cwe_data, dict):
+                cwe_id = cwe_data.get("cwe_id", "")
+                if cwe_id:
+                    cwes.append(cwe_id)
+            elif isinstance(cwe_data, str):
+                cwes.append(cwe_data)
+        return cwes if cwes else None
+
+    @field_validator("cvss", mode="before")
+    @classmethod
+    def parse_cvss(cls, v: Any, info: Any) -> Optional[CVSS]:
+        if not v:
+            return None
+        # Let the CVSS model handle the validation and parsing
+        try:
+            return CVSS.model_validate(v)
+        except Exception:
+            return None
+
+    @model_validator(mode="before")
+    @classmethod
+    def parse_cvss_severity(cls, data: Any) -> Any:
+        if isinstance(data, dict) and "cvss_severity" in data:
+            cvss_severity = data.pop("cvss_severity")
+            if cvss_severity:
+                if "cvss_v4" in cvss_severity:
+                    data["cvss"] = CVSS(string=cvss_severity["cvss_v4"])
+                elif "cvss_v3" in cvss_severity:
+                    data["cvss"] = CVSS(string=cvss_severity["cvss_v3"])
+        return data
+
+    def __str__(self) -> str:
+        return f"{self.ghsa_id}: {self.summary} ({self.severity})"
+
+    def __repr__(self) -> str:
+        vulns_repr = f"[{len(self.vulnerabilities)} vulnerabilities]"
+        desc_preview = (
+            self.description[:100] + "..."
+            if self.description and len(self.description) > 100
+            else self.description
+        )
+
+        return (
+            f"Advisory(\n"
+            f"  ghsa_id={self.ghsa_id!r},\n"
+            f"  cve_id={self.cve_id!r},\n"
+            f"  summary={self.summary!r},\n"
+            f"  severity={self.severity!r},\n"
+            f"  published_at={self.published_at!r},\n"
+            f"  vulnerabilities={vulns_repr},\n"
+            f"  description={desc_preview!r},\n"
+            f"  source_code_location={self.source_code_location!r},\n"
+            f"  cwes={self.cwes!r},\n"
+            f"  references={self.references!r}\n"
+            f")"
+        )
+
+    @property
+    def has_cve(self) -> bool:
+        """Check if the advisory has an associated CVE."""
+        return self.cve_id is not None and str(self.cve_id) != ""
+
+    @computed_field(return_type=str)
+    def vuln_id(self) -> str:
+        """Canonical vulnerability ID for the system, always a CVE when available, else GHSA."""
+        if self.cve_id is not None:
+            return str(self.cve_id)
+        return str(self.ghsa_id)
+
+    @property
+    def affected_packages(self) -> list[Package]:
+        """Get all unique packages affected by this advisory."""
+        packages = []
+        seen = set()
+        for vuln in self.vulnerabilities:
+            key = (vuln.package.name, vuln.package.ecosystem)
+            if key not in seen:
+                packages.append(vuln.package)
+                seen.add(key)
+        return packages
+
+    @property
+    def repository_url(self) -> str:
+        """Get the source code for the advisory."""
+        if not self.source_code_location:
+            self.source_code_location = self._get_repository_url_from_description()
+            if not self.source_code_location:
+                raise NoSourceCodeLocationFound(
+                    "No source code location found in advisory"
+                )
+        return self.source_code_location
+
+    def _get_repository_url_from_description(self) -> Optional[str]:
+        """Extract repository URL from description. Placeholder implementation."""
+        # TODO: Implement proper repository URL extraction from description
+        return None

ghsa_client-0.1.0/src/ghsa_client/models/base.py

@@ -0,0 +1,141 @@
+"""Base models for GHSA operations."""
+
+import re
+from typing import ClassVar, Optional, Any, List
+from pydantic import BaseModel, field_validator
+
+
+class CVE_ID(BaseModel):
+    """Strongly-typed CVE identifier with validation.
+    CVE IDs follow the format: CVE-YYYY-NNNN+, where NNNN can be 4 or more digits.
+    """
+
+    id: str
+
+    PATTERN: ClassVar[re.Pattern] = re.compile(r"^CVE-\d{4}-\d{4,}$", re.IGNORECASE)
+
+    def __init__(self, id: Optional[str] = None, **data: Any) -> None:
+        if id is not None:
+            data["id"] = id
+        elif "id" not in data:
+            raise ValueError("CVE ID cannot be None")
+        super().__init__(**data)
+
+    @field_validator("id", mode="before")
+    @classmethod
+    def validate_id(cls, value: Any) -> str:
+        if not isinstance(value, str):
+            raise ValueError(
+                f"CVE ID must be a string, got {type(value).__name__}"
+            )
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError("CVE ID cannot be empty")
+        if not cls.PATTERN.match(normalized):
+            raise ValueError(
+                f"Invalid CVE ID format: '{normalized}'. Expected CVE-YYYY-NNNN (e.g., CVE-2024-12345)"
+            )
+        # Normalize to upper-case prefix and keep the rest as-is
+        parts = normalized.split("-", 2)
+        return f"CVE-{parts[1]}-{parts[2]}"
+
+    def __str__(self) -> str:
+        return self.id
+
+    def __repr__(self) -> str:
+        return f"CVE_ID('{self.id}')"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, CVE_ID):
+            return self.id == other.id
+        if not isinstance(other, str):
+            return False
+        try:
+            other_cve = CVE_ID(id=other)
+            return self.id == other_cve.id
+        except ValueError:
+            return False
+
+    def __hash__(self) -> int:
+        return hash(self.id)
+
+
+class CVSSVector(BaseModel):
+    """CVSS vector representation."""
+    vector: str
+
+
+class CVSS(BaseModel):
+    """CVSS score representation."""
+    string: Optional[str] = None
+    score: Optional[float] = None
+    vector: Optional[CVSSVector] = None
+
+
+class Package(BaseModel):
+    """Package representation."""
+    name: str
+    ecosystem: str
+
+
+class VersionPredicate(BaseModel):
+    """Version predicate for vulnerability ranges."""
+    predicate: str
+    
+    @classmethod
+    def from_str(cls, predicate_str: str) -> "VersionPredicate":
+        """Create a VersionPredicate from a string."""
+        return cls(predicate=predicate_str)
+    
+    def __str__(self) -> str:
+        return self.predicate
+
+
+class Vulnerability(BaseModel):
+    """Represents a vulnerability within an advisory."""
+
+    package: Package
+    vulnerable_version_range: List[VersionPredicate] = []
+    first_patched_version: Optional[str] = None
+
+    @field_validator("vulnerable_version_range", mode="before")
+    @classmethod
+    def parse_vulnerable_version_range(cls, v: Any) -> List[VersionPredicate]:
+        if not isinstance(v, str):
+            raise ValueError(f"Invalid vulnerable version range: {v}")
+        # Handle single predicate string
+        if "," not in v:
+            return [VersionPredicate.from_str(v)]
+        # Handle comma-separated predicates
+        return [
+            VersionPredicate.from_str(predicate.strip()) for predicate in v.split(",")
+        ]
+
+    def __str__(self) -> str:
+        patched = (
+            f" → {self.first_patched_version}"
+            if self.first_patched_version is not None
+            else ""
+        )
+        version_range_str = (
+            "[" + ", ".join(str(pred) for pred in self.vulnerable_version_range) + "]"
+        )
+        return f"{self.package}: {version_range_str}{patched}"
+
+    def __repr__(self) -> str:
+        version_range_str = (
+            "[" + ", ".join(str(pred) for pred in self.vulnerable_version_range) + "]"
+        )
+        return (
+            f"Vulnerability(package={self.package!r}, "
+            f"vulnerable_version_range={version_range_str}, "
+            f"first_patched_version={self.first_patched_version!r})"
+        )
+
+
+class GitCommit(BaseModel):
+    """Git commit representation."""
+    sha: str
+    message: Optional[str] = None
+    author: Optional[str] = None
+    date: Optional[str] = None

ghsa_client-0.1.0/src/ghsa_client/models/ghsa_id.py

@@ -0,0 +1,72 @@
+"""GHSA ID model with validation."""
+
+import re
+from typing import ClassVar, Optional, Any
+from pydantic import BaseModel, field_validator
+
+
+class InvalidGHSAIDError(Exception):
+    """Raised when GHSA ID format is invalid."""
+
+    pass
+
+
+class GHSA_ID(BaseModel):
+    """
+    A strongly-typed GHSA identifier with proper validation.
+    GHSA IDs follow the format: GHSA-xxxx-xxxx-xxxx where x is an alphanumeric character [0-9a-z].
+    """
+
+    id: str
+
+    PATTERN: ClassVar[re.Pattern] = re.compile(
+        r"^GHSA-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}$", re.IGNORECASE
+    )
+
+    def __init__(self, id: Optional[str] = None, **data: Any) -> None:
+        if id is not None:
+            data["id"] = id
+        elif "id" not in data:
+            raise InvalidGHSAIDError("GHSA ID cannot be None")
+        super().__init__(**data)
+
+    @field_validator("id", mode="before")
+    @classmethod
+    def validate_id(cls, v: Any) -> str:
+        if not isinstance(v, str):
+            raise InvalidGHSAIDError(
+                f"GHSA ID must be a string, got {type(v).__name__}"
+            )
+        normalized_id = v.strip()
+        if not normalized_id:
+            raise InvalidGHSAIDError("GHSA ID cannot be empty")
+        if not cls.PATTERN.match(normalized_id):
+            raise InvalidGHSAIDError(
+                f"Invalid GHSA ID format: '{normalized_id}'. "
+                f"Expected format: GHSA-xxxx-xxxx-xxxx where x is alphanumeric (e.g., GHSA-gq96-8w38-hhj2)"
+            )
+        return "GHSA-" + normalized_id[5:].lower()
+
+    @property
+    def ghsa_id(self) -> "GHSA_ID":
+        return self
+
+    def __str__(self) -> str:
+        return self.id
+
+    def __repr__(self) -> str:
+        return f"GHSA_ID('{self.id}')"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, GHSA_ID):
+            return self.id == other.id
+        if not isinstance(other, str):
+            return False
+        try:
+            other_ghsa = GHSA_ID(id=other)
+            return self.id == other_ghsa.id
+        except (InvalidGHSAIDError, Exception):
+            return False
+
+    def __hash__(self) -> int:
+        return hash(self.id)

ghsa_client-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for ghsa-client package."""

ghsa_client-0.1.0/tests/test_client.py

@@ -0,0 +1,76 @@
+"""Tests for GHSA client."""
+
+import pytest
+import logging
+from unittest.mock import patch, MagicMock
+
+from ghsa_client import GHSAClient, GHSA_ID, RateLimitExceeded
+
+
+class TestGHSAClient:
+    def test_initialization_without_token(self) -> None:
+        """Test client initialization without GitHub token."""
+        logger = logging.getLogger(__name__)
+        client = GHSAClient(logger=logger)
+        assert client.base_url == "https://api.github.com"
+        assert "Authorization" not in client.session.headers
+    
+    def test_initialization_with_token(self) -> None:
+        """Test client initialization with GitHub token."""
+        logger = logging.getLogger(__name__)
+        with patch.dict("os.environ", {"GITHUB_TOKEN": "test-token"}):
+            client = GHSAClient(logger=logger)
+            assert client.session.headers["Authorization"] == "Bearer test-token"
+    
+    def test_initialization_with_custom_url(self) -> None:
+        """Test client initialization with custom base URL."""
+        logger = logging.getLogger(__name__)
+        client = GHSAClient(logger=logger, base_url="https://custom.github.com")
+        assert client.base_url == "https://custom.github.com"
+    
+    @patch('ghsa_client.client.requests.Session.get')
+    def test_get_advisory_success(self, mock_get: MagicMock) -> None:
+        """Test successful advisory retrieval."""
+        logger = logging.getLogger(__name__)
+        client = GHSAClient(logger=logger)
+        
+        # Mock rate limit response
+        mock_rate_limit_response = MagicMock()
+        mock_rate_limit_response.json.return_value = {
+            "resources": {
+                "core": {
+                    "remaining": 5000,
+                    "reset": 1234567890
+                }
+            }
+        }
+        mock_rate_limit_response.raise_for_status.return_value = None
+        
+        # Mock advisory response
+        mock_advisory_response = MagicMock()
+        mock_advisory_response.json.return_value = {
+            "ghsa_id": "GHSA-gq96-8w38-hhj2",
+            "summary": "Test advisory",
+            "severity": "high",
+            "published_at": "2024-01-01T00:00:00Z",
+            "vulnerabilities": []
+        }
+        mock_advisory_response.raise_for_status.return_value = None
+        
+        # Configure mock to return different responses for different URLs
+        def side_effect(*args: object, **kwargs: object) -> MagicMock:
+            url = str(args[0]) if args else ""
+            if "rate_limit" in url:
+                return mock_rate_limit_response
+            else:
+                return mock_advisory_response
+        
+        mock_get.side_effect = side_effect
+        
+        # Test
+        ghsa_id = GHSA_ID("GHSA-gq96-8w38-hhj2")
+        advisory = client.get_advisory(ghsa_id)
+        
+        assert advisory.ghsa_id.id == "GHSA-gq96-8w38-hhj2"
+        assert advisory.summary == "Test advisory"
+        assert advisory.severity == "high"

ghsa_client-0.1.0/tests/test_models.py

@@ -0,0 +1,87 @@
+"""Tests for GHSA models."""
+
+import pytest
+from ghsa_client import GHSA_ID, Advisory
+from ghsa_client.models import CVE_ID, InvalidGHSAIDError, Package, Vulnerability, VersionPredicate
+
+
+class TestGHSA_ID:
+    def test_valid_ghsa_id(self) -> None:
+        """Test valid GHSA ID creation."""
+        ghsa_id = GHSA_ID("GHSA-gq96-8w38-hhj2")
+        assert ghsa_id.id == "GHSA-gq96-8w38-hhj2"
+    
+    def test_invalid_ghsa_id_format(self) -> None:
+        """Test invalid GHSA ID format raises error."""
+        with pytest.raises(InvalidGHSAIDError):
+            GHSA_ID("invalid-id")
+    
+    def test_ghsa_id_string_conversion(self) -> None:
+        """Test GHSA ID string conversion."""
+        ghsa_id = GHSA_ID("GHSA-gq96-8w38-hhj2")
+        assert str(ghsa_id) == "GHSA-gq96-8w38-hhj2"
+    
+    def test_ghsa_id_equality(self) -> None:
+        """Test GHSA ID equality."""
+        ghsa_id1 = GHSA_ID("GHSA-gq96-8w38-hhj2")
+        ghsa_id2 = GHSA_ID("GHSA-gq96-8w38-hhj2")
+        assert ghsa_id1 == ghsa_id2
+        assert ghsa_id1 == "GHSA-gq96-8w38-hhj2"
+
+
+class TestCVE_ID:
+    def test_valid_cve_id(self) -> None:
+        """Test valid CVE ID creation."""
+        cve_id = CVE_ID("CVE-2024-12345")
+        assert cve_id.id == "CVE-2024-12345"
+    
+    def test_invalid_cve_id_format(self) -> None:
+        """Test invalid CVE ID format raises error."""
+        with pytest.raises(ValueError):
+            CVE_ID("invalid-id")
+    
+    def test_cve_id_string_conversion(self) -> None:
+        """Test CVE ID string conversion."""
+        cve_id = CVE_ID("CVE-2024-12345")
+        assert str(cve_id) == "CVE-2024-12345"
+
+
+class TestAdvisory:
+    def test_advisory_creation(self) -> None:
+        """Test advisory model creation."""
+        ghsa_id = GHSA_ID("GHSA-gq96-8w38-hhj2")
+        package = Package(name="test-package", ecosystem="npm")
+        vulnerability = Vulnerability(package=package)
+        
+        advisory = Advisory(
+            ghsa_id=ghsa_id,
+            summary="Test advisory",
+            severity="high",
+            published_at="2024-01-01T00:00:00Z",
+            vulnerabilities=[vulnerability]
+        )
+        
+        assert advisory.ghsa_id == ghsa_id
+        assert advisory.summary == "Test advisory"
+        assert advisory.severity == "high"
+        assert len(advisory.vulnerabilities) == 1
+    
+    def test_advisory_has_cve_property(self) -> None:
+        """Test advisory has_cve property."""
+        ghsa_id = GHSA_ID("GHSA-gq96-8w38-hhj2")
+        package = Package(name="test-package", ecosystem="npm")
+        vulnerability = Vulnerability(package=package)
+        
+        # Advisory without CVE
+        advisory = Advisory(
+            ghsa_id=ghsa_id,
+            summary="Test advisory",
+            severity="high",
+            published_at="2024-01-01T00:00:00Z",
+            vulnerabilities=[vulnerability]
+        )
+        assert not advisory.has_cve
+        
+        # Advisory with CVE
+        advisory.cve_id = CVE_ID("CVE-2024-12345")
+        assert advisory.has_cve