nvd-client 0.1.1__py3-none-any.whl

nvd_client/__init__.py

@@ -0,0 +1,15 @@
+from .exceptions import InvalidParametersError, InvalidCVEIDError, InvalidDateFormatError
+from .api import NvdApi
+
+__version__ = '0.1.0'
+__author__ = 'Ahur4'
+__author_email__ = 'ahur4.rahmani@gmail.com'
+__license__ = 'MIT'
+__copyright__ = 'Copyright 2024, Ahur4'
+
+__all__ = [
+    "InvalidDateFormatError",
+    "InvalidCVEIDError",
+    "InvalidParametersError",
+    "NvdApi",
+]

nvd_client/api.py

@@ -0,0 +1,305 @@
+from typing import Dict, List, Optional, Union
+
+import requests
+
+from nvd_client.utils import validate_and_convert_dates, validate_cve_id
+
+
+class NvdApi:
+    """
+    A class to interact with the NVD API for fetching CVE data.
+
+    Attributes:
+        api_key (Optional[str]): The API key for authenticating requests.
+        api_key (Optional[str]): The Socks5 Proxy.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, proxy: Optional[str] = None) -> None:
+        """
+        Initialize the NvdApi class.
+
+        Args:
+            api_key (Optional[str]): The API key for authenticating requests. Default is None.
+            api_key (Optional[str]): The Socks5 Proxy.
+        """
+        self.proxy: Optional[str] = proxy
+        self.api_key: Optional[str] = api_key
+        self.base_url_cve: str = 'https://services.nvd.nist.gov/rest/json/cves/2.0'
+        self.base_url_cpe: str = 'https://services.nvd.nist.gov/rest/json/cpematch/2.0'
+
+    def __str__(self) -> str:
+        """
+        Return a string representation of the NvdApi class.
+
+        Returns:
+            str: A string representation of the class.
+        """
+        return "What are you looking for?"
+
+    @staticmethod
+    def _verifier(params: Dict[str, Union[str, int]]) -> str:
+        """
+        Construct query string from parameters dictionary.
+
+        Args:
+            params (Dict[str, Union[str, int]]): The parameters' dictionary.
+
+        Returns:
+            str: The query string constructed from the parameters.
+        """
+        return "&".join([f"{k}={v}" for k, v in params.items()])
+
+    def _make_request(
+            self,
+            params: Optional[Dict[str, Union[str, int]]] = None,
+            type_of: str = "cve",
+            proxy: Optional[str] = None,
+    ) -> Optional[Dict[str, Union[str, int, List, Dict]]]:
+        """
+        Make a request to the NVD API with the provided parameters.
+
+        Args:
+            params (Optional[Dict[str, Union[str, int]]]): The parameters for the API request. Default is None.
+            type_of (str): The parameters for the type of used api. default is cve.
+
+        Returns: Optional[Dict[str, Union[str, int, List, Dict]]]: The JSON response from the API, or None if an
+        error occurred.
+        """
+        try:
+            parameters = self._verifier(params or {})
+            if type_of == "cve":
+                link = f"{self.base_url_cve}?{parameters}"
+            else:
+                link = f"{self.base_url_cpe}?{parameters}"
+            headers = {'apiKey': self.api_key} if self.api_key else {}
+            if self.proxy:
+                response = requests.get(link, headers=headers, proxies={"http": self.proxy, "https": self.proxy})
+            elif proxy:
+                response = requests.get(link, headers=headers, proxies={"http": proxy, "https": proxy})
+            else:
+                response = requests.get(link, headers=headers)
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            return None
+
+    def get_all_cves(self, per_page: int = 2000, offset: int = 0, proxy: Optional[str] = None) -> Optional[Dict[str, Union[str, int, List, Dict]]]:
+        """
+        Fetch all CVEs with pagination.
+
+        Args:
+            per_page (int): The number of results per page. Default is 2000.
+            offset (int): The starting index for the results. Default is 0.
+            proxy (str): The proxy to use. Default is None.
+
+        Returns: Optional[Dict[str, Union[str, int, List, Dict]]]: The JSON response from the API, or None if an
+        error occurred.
+        """
+        parameters = {
+            'resultsPerPage': per_page,
+            'startIndex': offset
+        }
+        if proxy:
+            return self._make_request(params=parameters, proxy=proxy)
+        return self._make_request(params=parameters)
+
+    def get_cve_by_id(self, cve_id: str, proxy: Optional[str] = None) -> Optional[Dict[str, Union[str, int, List, Dict]]]:
+        """
+        Fetch a CVE by its ID.
+
+        Args:
+            cve_id (str): The CVE ID to fetch.
+            proxy (str): The proxy to use. Default is None.
+
+        Returns: Optional[Dict[str, Union[str, int, List, Dict]]]: The JSON response from the API, or None if an
+        error occurred.
+        """
+        if validate_cve_id(cve_id):
+            parameters = {"cveId": cve_id}
+            if proxy:
+                return self._make_request(params=parameters, proxy=proxy)
+            return self._make_request(params=parameters)
+
+    def get_cve_by_date(
+            self,
+            per_page: int = 2000,
+            offset: int = 0,
+            publish_start_date: Optional[str] = None,
+            publish_end_date: Optional[str] = None,
+            modify_start_date: Optional[str] = None,
+            modify_end_date: Optional[str] = None,
+            proxy: Optional[str] = None,
+    ) -> Optional[Dict[str, Union[str, int, List, Dict]]]:
+        """
+        Fetch CVEs by publication or modification date.
+
+        Args:
+            per_page (int): The number of results per page. Default is 2000.
+            offset (int): The starting index for the results. Default is 0.
+            publish_start_date (Optional[str]): The start date for the publication date range. Default is None.
+            publish_end_date (Optional[str]): The end date for the publication date range. Default is None.
+            modify_start_date (Optional[str]): The start date for the modification date range. Default is None.
+            modify_end_date (Optional[str]): The end date for the modification date range. Default is None.
+            proxy (str): The proxy to use. Default is None.
+
+        Returns: Optional[Dict[str, Union[str, int, List, Dict]]]: The JSON response from the API, or None if an
+        error occurred.
+        """
+        parameters: Dict[str, Union[str, int, List, Dict]] = {}
+
+        publish_start_date, publish_end_date = validate_and_convert_dates(
+            start_date=publish_start_date,
+            end_date=publish_end_date,
+            param_names=["publish_start_date", "publish_end_date"]
+        )
+
+        modify_start_date, modify_end_date = validate_and_convert_dates(
+            start_date=modify_start_date,
+            end_date=modify_end_date,
+            param_names=["modify_start_date", "modify_end_date"]
+        )
+
+        if publish_start_date and publish_end_date:
+            parameters.update(pubStartDate=publish_start_date, pubEndDate=publish_end_date)
+
+        if modify_start_date and modify_end_date:
+            parameters.update(lastModStartDate=modify_start_date, lastModEndDate=modify_end_date)
+
+        # Add more parameters as needed
+        parameters.update(resultsPerPage=per_page, startIndex=offset)
+
+        if proxy:
+            return self._make_request(params=parameters, proxy=proxy)
+        return self._make_request(params=parameters)
+
+    def get_cve_by_cpe(
+            self,
+            cpe_name: str,
+            per_page: int = 2000,
+            offset: int = 0,
+            publish_start_date: Optional[str] = None,
+            publish_end_date: Optional[str] = None,
+            modify_start_date: Optional[str] = None,
+            modify_end_date: Optional[str] = None,
+            proxy: Optional[str] = None,
+    ) -> Optional[Dict[str, Union[str, int, List, Dict]]]:
+        """
+        Fetch CVEs by CpeId.
+
+        Args:
+            cpe_name (str): The CPE name to fetch.
+            per_page (int): The number of results per page. Default is 2000.
+            offset (int): The starting index for the results. Default is 0.
+            publish_start_date (Optional[str]): The start date for the publication date range. Default is None.
+            publish_end_date (Optional[str]): The end date for the publication date range. Default is None.
+            modify_start_date (Optional[str]): The start date for the modification date range. Default is None.
+            modify_end_date (Optional[str]): The end date for the modification date range. Default is None.
+            proxy (str): The proxy to use. Default is None.
+
+        Returns: Optional[Dict[str, Union[str, int, List, Dict]]]: The JSON response from the API, or None if an
+        error occurred.
+        """
+        parameters = {}
+
+        publish_start_date, publish_end_date = validate_and_convert_dates(
+            start_date=publish_start_date,
+            end_date=publish_end_date,
+            param_names=["publish_start_date", "publish_end_date"]
+        )
+
+        modify_start_date, modify_end_date = validate_and_convert_dates(
+            start_date=modify_start_date,
+            end_date=modify_end_date,
+            param_names=["modify_start_date", "modify_end_date"]
+        )
+
+        if publish_start_date and publish_end_date:
+            parameters.update(pubStartDate=publish_start_date, pubEndDate=publish_end_date)
+
+        if modify_start_date and modify_end_date:
+            parameters.update(lastModStartDate=modify_start_date, lastModEndDate=modify_end_date)
+
+        parameters.update(resultsPerPage=per_page, startIndex=offset, cpeName=cpe_name)
+
+        if proxy:
+            return self._make_request(params=parameters, proxy=proxy)
+        return self._make_request(params=parameters)
+
+    def get_cpes_by_cve(
+            self,
+            cve_id: str,
+            per_page: int = 500,
+            offset: int = 0,
+            proxy: Optional[str] = None,
+    ) -> Optional[Dict[str, Union[str, int, List, Dict]]]:
+        """
+        Fetch CPEs by CveId.
+
+        Args:
+            cve_id (str): The CVE ID to fetch.
+            per_page (int): The number of results per page. Default and Maximum is 500.
+            offset (int): The starting index for the results. Default is 0.
+            proxy (str): The proxy to use. Default is None.
+
+        Returns: List[Union[Dict[str, Any], Any]]: The JSON response from the API, or None if an
+        error occurred.
+        """
+        if validate_cve_id(cve_id):
+            parameters = {}
+            parameters.update(resultsPerPage=per_page, startIndex=offset, cveId=cve_id)
+
+            if proxy:
+                return self._make_request(params=parameters, type_of="cpe", proxy=proxy)
+            return self._make_request(params=parameters, type_of="cpe")
+
+    def get_cpes_by_criteria(
+            self,
+            criteria: str,
+            per_page: int = 500,
+            offset: int = 0,
+            proxy: Optional[str] = None,
+    ) -> Optional[Dict[str, Union[str, int, List, Dict]]]:
+        """
+        Fetch CPEs by CveId.
+
+        Args:
+            criteria (str): The Criteria to fetch.
+            per_page (int): The number of results per page. Default and Maximum is 500.
+            offset (int): The starting index for the results. Default is 0.
+            proxy (str): The proxy to use. Default is None.
+
+        Returns: List[Union[Dict[str, Any], Any]]: The JSON response from the API, or None if an
+        error occurred.
+        """
+        parameters = {}
+        parameters.update(resultsPerPage=per_page, startIndex=offset, matchStringSearch=criteria)
+
+        if proxy:
+            return self._make_request(params=parameters, type_of="cpe", proxy=proxy)
+        return self._make_request(params=parameters, type_of="cpe")
+
+    def get_cpes_by_criteria_name_id(
+            self,
+            criteria_name_id: str,
+            per_page: int = 500,
+            offset: int = 0,
+            proxy: Optional[str] = None,
+    ) -> Optional[Dict[str, Union[str, int, List, Dict]]]:
+        """
+        Fetch CPEs by CveId.
+
+        Args:
+            criteria_name_id (str): The Criteria Name ID to fetch.
+            per_page (int): The number of results per page. Default and Maximum is 500.
+            offset (int): The starting index for the results. Default is 0.
+            proxy (str): The proxy to use. Default is None.
+
+        Returns: List[Union[Dict[str, Any], Any]]: The JSON response from the API, or None if an
+        error occurred.
+        """
+        parameters = {}
+        parameters.update(resultsPerPage=per_page, startIndex=offset, matchCriteriaId=criteria_name_id)
+
+        if proxy:
+            return self._make_request(params=parameters, type_of="cpe", proxy=proxy)
+        return self._make_request(params=parameters, type_of="cpe")

nvd_client/exceptions.py

@@ -0,0 +1,40 @@
+from typing import List
+
+
+class InvalidDateFormatError(Exception):
+    """Exception raised for errors in the input date format."""
+
+    def __init__(self, date_str, message="Invalid date format. Please use YYYY-MM-DD."):
+        self.date_str = date_str
+        self.message = message
+        super().__init__(self.message)
+
+    def __str__(self):
+        return f'{self.date_str} -> {self.message}'
+
+
+class InvalidParametersError(Exception):
+    """Exception raised for invalid parameters."""
+
+    def __init__(
+            self,
+            missing_params: List[str],
+            message="Invalid parameter combination. Both parameters are required."
+    ):
+        self.missing_params = missing_params
+        self.message = message
+        super().__init__(self.message)
+
+    def __str__(self):
+        return f'Missing or incomplete parameters: {", ".join(self.missing_params)} -> {self.message}'
+
+
+class InvalidCVEIDError(Exception):
+    """Exception raised for errors in the input CVE ID."""
+    def __init__(self, cve_id: str, message="Invalid CVE ID format. Please use CVE-YYYY-NNNN format."):
+        self.cve_id = cve_id
+        self.message = message
+        super().__init__(self.message)
+
+    def __str__(self):
+        return f'{self.cve_id} -> {self.message}'

nvd_client/utils.py

@@ -0,0 +1,48 @@
+import re
+from datetime import datetime
+from .exceptions import InvalidDateFormatError, InvalidParametersError, InvalidCVEIDError
+from typing import Optional, List
+
+
+def validate_date_format(date_str):
+    # Define the regex pattern for YYYY-MM-DD format
+    pattern = r'^\d{4}-\d{2}-\d{2}$'
+    # Check if the date_str matches the pattern
+    if re.match(pattern, date_str):
+        try:
+            # Try to parse the date to ensure it's a valid date
+            datetime.strptime(date_str, '%Y-%m-%d')
+            return True
+        except ValueError:
+            return False
+    else:
+        return False
+
+
+def convert_date_to_iso(date_str):
+    if validate_date_format(date_str):
+        # Parse the input date
+        date = datetime.strptime(date_str, '%Y-%m-%d')
+        # Convert to the desired format
+        iso_format_date = date.strftime('%Y-%m-%dT%H:%M:%S.%f')[:-3]
+        return iso_format_date
+    else:
+        raise InvalidDateFormatError(date_str)
+
+
+def validate_and_convert_dates(start_date: Optional[str], end_date: Optional[str], param_names: List[str]):
+    if start_date and end_date:
+        return convert_date_to_iso(start_date), convert_date_to_iso(end_date)
+    elif start_date or end_date:
+        raise InvalidParametersError(missing_params=param_names)
+    return None, None
+
+
+def validate_cve_id(cve_id: str) -> bool:
+    # Define the regex pattern for CVE-YYYY-NNNN format
+    pattern = r'^CVE-\d{4}-\d{4,}$'
+    # Check if the cve_id matches the pattern
+    if re.match(pattern, cve_id):
+        return True
+    else:
+        raise InvalidCVEIDError(cve_id)

nvd_client-0.1.1.dist-info/LICENSE

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

nvd_client-0.1.1.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.1
+Name: nvd-client
+Version: 0.1.1
+Summary: A Python client for interacting with the National Vulnerability Database (NVD) API to fetch CVE data.
+Home-page: https://github.com/ahur4/nvd-client
+Author: Ahur4
+Author-email: ahur4.rahmani@gmail.com
+Keywords: vulnerability,nvd,national vulnerability database,nvd_client,nvd_client-api,ahur4,ahura rahmani,redteam,soc,vulnerability assessment,penetration testing
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: certifi ==2024.6.2
+Requires-Dist: charset-normalizer ==3.3.2
+Requires-Dist: idna ==3.7
+Requires-Dist: requests[socks] ==2.32.3
+Requires-Dist: urllib3 ==2.2.1
+
+
+# NVD API Client
+
+![PyPI](https://img.shields.io/pypi/v/nvd-client)
+![Daily Downloads](https://img.shields.io/pypi/dd/nvd-client)
+![Monthly Downloads](https://img.shields.io/pypi/dm/nvd-client)
+[![Telegram-Channel](https://img.shields.io/badge/Telegram--Channel-Ahura_Rahmani-blue)](https://t.me/Ahur4_Rahmani)
+
+
+A Python client for interacting with the National Vulnerability Database (NVD) API to fetch CVE data.
+
+## Features
+
+- Fetch all CVEs with pagination
+- Fetch CVE by its ID
+- Fetch CVEs by publication or modification date
+- Fetch CVEs by CPE name
+- Other features coming soon...
+
+## Installation
+
+You can install the package using pip:
+
+```sh
+pip install nvd_client
+```
+
+## Usage
+
+```python
+from nvd_client import NvdApi
+
+# Initialize the API client
+api_key = "your_api_key_here"
+nvd_api = NvdApi(api_key)
+
+# Fetch all CVEs
+cves = nvd_api.get_all_cves(per_page=100, offset=0)
+print(cves)
+
+# Fetch a CVE by ID
+cve = nvd_api.get_cve_by_id(cve_id="CVE-2024-30078")
+print(cve)
+
+# Fetch CVEs by publish or modify date range
+cves_by_date = nvd_api.get_cve_by_date(
+    per_page=100,
+    offset=0,
+    publish_start_date="2021-01-01",
+    publish_end_date="2021-12-31"
+)
+print(cves_by_date)
+
+# Fetch CVEs by CPE name
+cves_by_cpe = nvd_api.get_cve_by_cpe(
+    cpe_name="cpe:2.3:o:microsoft:windows_10:1607:*:*:*:*:*:*:*",
+    per_page=100,
+    offset=0
+)
+print(cves_by_cpe)
+```
+
+## Author
+
+- Author: Ahur4
+
+- Telegram: [@Ahura_rahmani](https://t.me/Ahura_rahmani)
+
+## License
+
+This project is licensed under the MIT License. See the `LICENSE` file for details.
+
+
+### Explanation:
+1. **Features**: Lists the main functionalities provided by the module.
+2. **Installation**: Provides instructions for installing the package using pip from PyPI.
+3. **Usage**: Gives examples of how to initialize the client and use its methods.
+4. **Author**: Provides your name and a link to your Telegram channel.
+5. **License**: States that the project is licensed under the MIT License.

nvd_client-0.1.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+nvd_client/__init__.py,sha256=JBBwBR214nMGV_ZG5dr06gNuL6Wu6EzneYLTLcjWTgo,392
+nvd_client/api.py,sha256=aOh19xUXzg08FtyXxJCEZsbkmwieqakVII2FxfKIzCM,12667
+nvd_client/exceptions.py,sha256=jah5qsid089419Cwq1fLY3SIgkdeGorj1daG3Z6qsOo,1314
+nvd_client/utils.py,sha256=GpN4v4ONQAijtxJL49sxpmkJs3SZMziCxMT9r7uwrEY,1645
+nvd_client-0.1.1.dist-info/LICENSE,sha256=sH516rZoWuam08PIkKJ7N9q8AR_KZZ67CttgY9Q5n7U,1081
+nvd_client-0.1.1.dist-info/METADATA,sha256=rRIJ_SLq-K0pMAAYGZuEPuVxULkKfL224mtMmCPxHqQ,2906
+nvd_client-0.1.1.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+nvd_client-0.1.1.dist-info/top_level.txt,sha256=Bt0KpXk1HXgHIzDg70YvgQaBzhBsBVwZHSAbTtsrOk4,11
+nvd_client-0.1.1.dist-info/RECORD,,

nvd_client-0.1.1.dist-info/WHEEL

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

nvd_client-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+nvd_client