cpe-search 0.1.4__tar.gz

cpe_search-0.1.4/.github/workflows/publish_pypi_package_on_new_release.yml

@@ -0,0 +1,47 @@
+name: 'Publish Package to PyPI on New Release'
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          cache: 'pip'
+          python-version: "3.10"
+      - name: Install Hatch
+        run: pip install hatch
+      - name: Build distributions
+        run: hatch build
+      - name: Upload dist as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - name: Download built distributions
+        uses: actions/download-artifact@v5
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          package-dir: dist/

cpe_search-0.1.4/.github/workflows/tests.yml

@@ -0,0 +1,30 @@
+name: 'Run Test Cases'
+
+on:
+  workflow_dispatch:
+  push:
+
+jobs:
+  run-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v3
+      - name: Set up Python and Pip
+        uses: actions/setup-python@v4
+        with:
+          cache: 'pip'
+          python-version: '3.10'
+      - name: Upgrade Pip
+        run: python3 -m pip install --upgrade pip
+      - name: Install tool
+        run: pip install .
+      - name: Build CPE dictionary
+        env:
+          NVD_API_KEY: ${{ secrets.NVD_API_KEY }}
+        run: NVD_API_KEY=$NVD_API_KEY cpe_search -u
+      - name: Test matching CPEs
+        run: python3 tests/test_cpes.py
+      # skip for now because of non-deterministic issues
+      # - name: Test CPE suggestions
+      #   run: python3 tests/test_cpe_suggestions.py

cpe_search-0.1.4/.gitignore

@@ -0,0 +1,5 @@
+cpe-search-dictionary.db3
+deprecated-cpes.json
+__pycache__/
+.vscode
+dist/

cpe_search-0.1.4/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+This file keeps track of all notable changes between the different versions of cpe_search.
+
+## v0.1.4 - 2025-11-27
+### Fixed
+- Fixed bug with `-` and `_` in queries preventing valid CPE matches
+
+## v0.1.3 - 2025-11-21
+### Fixed
+- Skip retrieval of deprecatedBy CPEs if NVD's dictionary does not contain this data
+
+## v0.1.2 - 2025-11-18
+### Fixed
+- GitHub workflow to publish PyPI package uses more recent action versions
+
+## v0.1.1 - 2025-11-18
+### Added
+- GitHub workflow to automatically publish a package to PyPI on new release
+
+## v0.1.0 - 2025-11-17
+### Added
+- Initial release

cpe_search-0.1.4/LICENSE

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

cpe_search-0.1.4/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: cpe_search
+Version: 0.1.4
+Summary: Search for Common Platform Enumeration (CPE) strings using software names and titles.
+Project-URL: Homepage, https://github.com/ra1nb0rn/cpe_search
+Project-URL: Documentation, https://github.com/ra1nb0rn/cpe_search
+Project-URL: Repository, https://github.com/ra1nb0rn/cpe_search
+Project-URL: Issues, https://github.com/ra1nb0rn/cpe_search/issues
+Author-email: Dustin Born <search.vulns1@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cpe,enumeration,match,nvd,platform,search,software
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: aiohttp
+Requires-Dist: aiolimiter
+Requires-Dist: requests
+Requires-Dist: ujson
+Provides-Extra: all
+Requires-Dist: aiohttp; extra == 'all'
+Requires-Dist: aiolimiter; extra == 'all'
+Requires-Dist: mariadb==1.1.12; extra == 'all'
+Requires-Dist: requests; extra == 'all'
+Requires-Dist: ujson; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: isort; extra == 'dev'
+Requires-Dist: pylint; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: mariadb
+Requires-Dist: mariadb==1.1.12; extra == 'mariadb'
+Description-Content-Type: text/markdown
+
+# cpe_search
+Search for Common Platform Enumeration (CPE) strings using software names and titles.
+
+## About
+*cpe_search* can be used to search for Common Platform Enumeration (CPE) strings using software names and titles. For example, if some tool discovered a web server running *Apache 2.4.39*, you can use this tool to easily and quickly retrieve the corresponding CPE 2.3 string *cpe:2.3:<zero-width  space>a:apache:http_server:2.4.39:\*\:\*:\*:\*:\*:\*:\**. Thereafter, the retrieved CPE string can be used to accurately search for vulnerabilities, e.g. via the [Online NVD](https://nvd.nist.gov/) or the [search_vulns](https://github.com/ra1nb0rn/search_vulns) tool.
+
+## Installation
+You can install cpe_search via pip directly:
+```
+pip3 install cpe_search
+```
+You can also clone this repository and run:
+```
+pip3 install .
+```
+
+Note that when *cpe_search* is used for the first time, it invokes a small setup routine that downloads all available CPEs from the [NVD's official API](https://nvd.nist.gov/developers/products) and precomputes the data utilized for searches in all subsequent runs. This may take a couple of minutes initially but is only done once. To speed this process up, you can provide an NVD API key if you have one (it's free). The API key can be provided with the ``-k`` argument or specified in an environment variable called ``NVD_API_KEY``. You can also set up and provide a configuration file, see `config.json`.
+
+## Usage
+*cpe_search*'s usage information is shown in the following:
+```
+usage: cpe_search [-h] [-u] [-k API_KEY] [-n NUMBER] [-q QUERY] [-v] [-c CONFIG]
+
+Search for CPEs using software names and titles -- Created by Dustin Born (ra1nb0rn)
+
+options:
+  -h, --help            show this help message and exit
+  -u, --update          Update the local CPE database
+  -k API_KEY, --api-key API_KEY
+                        NVD API key to use for updating the local CPE dictionary
+  -n NUMBER, --number NUMBER
+                        The number of CPEs to show in the similarity overview (default: 3)
+  -q QUERY, --query QUERY
+                        A query, i.e. textual software name / title like 'Apache 2.4.39' or 'Wordpress 5.7.2'
+  -v, --verbose         Be verbose and print status information
+  -c CONFIG, --config CONFIG
+                        A config file to use (default: config.json)
+```
+Note that when querying software with ``-q`` you have to put the software information in quotes if it contains any spaces. Also, you can use ``-q`` multiple times to make multiple queries at once. Moreover, the output can be piped to be directly useable with other tools. Here are some examples:
+* Query *Sudo 1.8.2* to retrieve its CPE 2.3 string:
+  ```bash
+  $ cpe_search -q "Sudo 1.8.2"
+  cpe:2.3:a:sudo_project:sudo:1.8.2:*:*:*:*:*:*:*
+  [('cpe:2.3:a:sudo_project:sudo:1.8.2:*:*:*:*:*:*:*', 0.8660254037844385),
+   ('cpe:2.3:a:sudo_project:sudo:1.3.0:*:*:*:*:*:*:*', 0.5773502691896256),
+   ('cpe:2.3:a:cryptography.io:cryptography:1.8.2:*:*:*:*:*:*:*',
+    0.4714045207910316)]
+  ```
+* Make a query and pipe the retrieved CPE to another tool:
+  ```bash
+  $ cpe_search -q "Windows 10 1809" | xargs echo
+  cpe:2.3:o:microsoft:windows_10:1809:*:*:*:*:*:*:*
+  ```
+* Make two queries at once:
+  ```bash
+  $ cpe_search -q "Apache 2.4.39" -q "Wordpress 5.7.2"
+  cpe:2.3:a:apache:http_server:2.4.39:*:*:*:*:*:*:*
+  [('cpe:2.3:a:apache:http_server:2.4.39:*:*:*:*:*:*:*', 0.6666664603674289),
+  ('cpe:2.3:a:apache:apache-airflow-providers-apache-spark:-:*:*:*:*:*:*:*',
+    0.600000153741923),
+  ('cpe:2.3:a:apache:apache-airflow-providers-apache-hive:-:*:*:*:*:*:*:*',
+    0.600000153741923)]
+
+  cpe:2.3:a:wordpress:wordpress:5.7.2:*:*:*:*:*:*:*
+  [('cpe:2.3:a:wordpress:wordpress:5.7.2:*:*:*:*:*:*:*', 0.9805804786431419),
+  ('cpe:2.3:a:wordpress:wordpress:-:*:*:*:*:*:*:*', 0.7071067811865475),
+  ('cpe:2.3:a:adenion:blog2social:5.7.2:*:*:*:*:wordpress:*:*',
+    0.6859944446591075)]
+  ```
+
+## License
+*cpe_search* is licensed under the MIT license, see [here](https://github.com/ra1nb0rn/cpe_search/blob/master/LICENSE).

cpe_search-0.1.4/README.md

@@ -0,0 +1,72 @@
+# cpe_search
+Search for Common Platform Enumeration (CPE) strings using software names and titles.
+
+## About
+*cpe_search* can be used to search for Common Platform Enumeration (CPE) strings using software names and titles. For example, if some tool discovered a web server running *Apache 2.4.39*, you can use this tool to easily and quickly retrieve the corresponding CPE 2.3 string *cpe:2.3:<zero-width  space>a:apache:http_server:2.4.39:\*\:\*:\*:\*:\*:\*:\**. Thereafter, the retrieved CPE string can be used to accurately search for vulnerabilities, e.g. via the [Online NVD](https://nvd.nist.gov/) or the [search_vulns](https://github.com/ra1nb0rn/search_vulns) tool.
+
+## Installation
+You can install cpe_search via pip directly:
+```
+pip3 install cpe_search
+```
+You can also clone this repository and run:
+```
+pip3 install .
+```
+
+Note that when *cpe_search* is used for the first time, it invokes a small setup routine that downloads all available CPEs from the [NVD's official API](https://nvd.nist.gov/developers/products) and precomputes the data utilized for searches in all subsequent runs. This may take a couple of minutes initially but is only done once. To speed this process up, you can provide an NVD API key if you have one (it's free). The API key can be provided with the ``-k`` argument or specified in an environment variable called ``NVD_API_KEY``. You can also set up and provide a configuration file, see `config.json`.
+
+## Usage
+*cpe_search*'s usage information is shown in the following:
+```
+usage: cpe_search [-h] [-u] [-k API_KEY] [-n NUMBER] [-q QUERY] [-v] [-c CONFIG]
+
+Search for CPEs using software names and titles -- Created by Dustin Born (ra1nb0rn)
+
+options:
+  -h, --help            show this help message and exit
+  -u, --update          Update the local CPE database
+  -k API_KEY, --api-key API_KEY
+                        NVD API key to use for updating the local CPE dictionary
+  -n NUMBER, --number NUMBER
+                        The number of CPEs to show in the similarity overview (default: 3)
+  -q QUERY, --query QUERY
+                        A query, i.e. textual software name / title like 'Apache 2.4.39' or 'Wordpress 5.7.2'
+  -v, --verbose         Be verbose and print status information
+  -c CONFIG, --config CONFIG
+                        A config file to use (default: config.json)
+```
+Note that when querying software with ``-q`` you have to put the software information in quotes if it contains any spaces. Also, you can use ``-q`` multiple times to make multiple queries at once. Moreover, the output can be piped to be directly useable with other tools. Here are some examples:
+* Query *Sudo 1.8.2* to retrieve its CPE 2.3 string:
+  ```bash
+  $ cpe_search -q "Sudo 1.8.2"
+  cpe:2.3:a:sudo_project:sudo:1.8.2:*:*:*:*:*:*:*
+  [('cpe:2.3:a:sudo_project:sudo:1.8.2:*:*:*:*:*:*:*', 0.8660254037844385),
+   ('cpe:2.3:a:sudo_project:sudo:1.3.0:*:*:*:*:*:*:*', 0.5773502691896256),
+   ('cpe:2.3:a:cryptography.io:cryptography:1.8.2:*:*:*:*:*:*:*',
+    0.4714045207910316)]
+  ```
+* Make a query and pipe the retrieved CPE to another tool:
+  ```bash
+  $ cpe_search -q "Windows 10 1809" | xargs echo
+  cpe:2.3:o:microsoft:windows_10:1809:*:*:*:*:*:*:*
+  ```
+* Make two queries at once:
+  ```bash
+  $ cpe_search -q "Apache 2.4.39" -q "Wordpress 5.7.2"
+  cpe:2.3:a:apache:http_server:2.4.39:*:*:*:*:*:*:*
+  [('cpe:2.3:a:apache:http_server:2.4.39:*:*:*:*:*:*:*', 0.6666664603674289),
+  ('cpe:2.3:a:apache:apache-airflow-providers-apache-spark:-:*:*:*:*:*:*:*',
+    0.600000153741923),
+  ('cpe:2.3:a:apache:apache-airflow-providers-apache-hive:-:*:*:*:*:*:*:*',
+    0.600000153741923)]
+
+  cpe:2.3:a:wordpress:wordpress:5.7.2:*:*:*:*:*:*:*
+  [('cpe:2.3:a:wordpress:wordpress:5.7.2:*:*:*:*:*:*:*', 0.9805804786431419),
+  ('cpe:2.3:a:wordpress:wordpress:-:*:*:*:*:*:*:*', 0.7071067811865475),
+  ('cpe:2.3:a:adenion:blog2social:5.7.2:*:*:*:*:wordpress:*:*',
+    0.6859944446591075)]
+  ```
+
+## License
+*cpe_search* is licensed under the MIT license, see [here](https://github.com/ra1nb0rn/cpe_search/blob/master/LICENSE).

cpe_search-0.1.4/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ['hatchling']
+build-backend = 'hatchling.build'
+
+[project]
+name = "cpe_search"
+version = "0.1.4"
+description = "Search for Common Platform Enumeration (CPE) strings using software names and titles."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    {name = "Dustin Born", email = "search.vulns1@gmail.com"}
+]
+keywords = ["software", "cpe", "platform", "search", "nvd", "match", "enumeration"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: System Administrators",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Topic :: Security",
+    "Topic :: System :: Systems Administration",
+]
+
+dependencies = [
+    "aiohttp",
+    "aiolimiter",
+    "requests",
+    "ujson",
+]
+
+[tool.hatch.build]
+exclude = [
+    "src/cpe_search/deprecated_cpes.json",
+    "src/cpe_search/cpe-search-dictionary.db3",
+]
+
+[project.optional-dependencies]
+mariadb = [
+    "mariadb==1.1.12",
+]
+dev = [
+    "black",
+    "isort",
+    "ruff",
+    "pylint",
+]
+all = [
+    "aiohttp",
+    "aiolimiter",
+    "mariadb==1.1.12",
+    "requests",
+    "ujson",
+]
+
+[project.scripts]
+cpe_search = "cpe_search.cpe_search:main"
+
+[project.urls]
+Homepage = "https://github.com/ra1nb0rn/cpe_search"
+Documentation = "https://github.com/ra1nb0rn/cpe_search"
+Repository = "https://github.com/ra1nb0rn/cpe_search"
+Issues = "https://github.com/ra1nb0rn/cpe_search/issues"
+
+[tool.black]
+line-length = 96
+target-version = ['py311']
+
+[tool.isort]
+profile = "black"
+
+[tool.ruff]
+line-length = 96
+target-version = "py311"
+select = ["ALL"]
+ignore = ["S104", "S201", "T201", "TRY201", "COM812", "E501", "TRY003", "EM101"]
+
+[tool.pylint."FORMAT"]
+max-line-length = 96

cpe_search-0.1.4/src/cpe_search/config.json

@@ -0,0 +1,10 @@
+{
+    "DEPRECATED_CPES_FILE": "deprecated-cpes.json",
+    "NVD_API_KEY": "",
+    "CPE_SEARCH_COUNT": 6,
+    "CPE_SEARCH_THRESHOLD": -1,
+    "DATABASE": {
+        "NAME": "cpe-search-dictionary.db3",
+        "TYPE": "sqlite"
+    }
+}

cpe_search-0.1.4/src/cpe_search/config_mariadb.json

@@ -0,0 +1,14 @@
+{
+    "DEPRECATED_CPES_FILE": "deprecated-cpes.json",
+    "NVD_API_KEY": "",
+    "CPE_SEARCH_COUNT": 6,
+    "CPE_SEARCH_THRESHOLD": -1,
+    "DATABASE": {
+        "NAME": "cpe_search_dictionary",
+        "TYPE": "mariadb",
+        "HOST": "localhost",
+        "USER": "search_vulns",
+        "PASSWORD": "",
+        "PORT": 3306
+    }
+}