chg: [doc] contribution added

README.md

@@ -1,7 +1,6 @@
 # CPE guesser
 
-CPE guesser is a command-line or web service to guess the CPE name based on one or more keyword(s).  Then the result can
+CPE Guesser is a command-line tool or web service designed to guess the CPE name based on one or more keywords. The resulting CPE can then be used with tools like [cve-search](https://github.com/cve-search/cve-search) or [vulnerability-lookup](https://github.com/cve-search/vulnerability-lookup) to perform actual searches using CPE names.
-be used against [cve-search](https://github.com/cve-search/cve-search) to do actual searches by CPE names.
 
 ## Requirements
 
@@ -10,11 +9,15 @@ be used against [cve-search](https://github.com/cve-search/cve-search) to do act
 
 ## Usage
 
-To use CPE guesser, you have to initialise the [Valkey](https://valkey.io/) database with `import.py`.
+To use CPE Guesser, you need to initialize the [Valkey](https://valkey.io/) database with `import.py`.
 
-Then you can use the software with `lookup.py` to find the most probable CPE matching the keywords provided.
+Once initialized, you can use the software with `lookup.py` to find the most probable CPE matching the provided keywords.
 
-Or by calling the Web server (After running `server.py`), example: `curl -s -X POST http://localhost:8000/search -d "{\"query\": [\"tomcat\"]}" | jq .`
+Alternatively, you can call the web server (after running `server.py`). For example:
+
+```bash
+curl -s -X POST http://localhost:8000/search -d '{"query": ["tomcat"]}' | jq .
+```
 
 ### Installation
 
@@ -76,18 +79,29 @@ curl -s -X POST https://cpe-guesser.cve-search.org/search -d "{\"query\": [\"out
 ]
 ```
 
+The endpoint `/unique` is available to retrieve only the best-matching CPE entry.
+
+```bash
+curl -s -X POST https://cpe-guesser.cve-search.org/unique -d "{\"query\": [\"outlook\", \"connector\"]}" | jq .
+```
+
+```json
+"cpe:2.3:a:oracle:corporate_time_outlook_connector"
+```
+
 ### Command line - `lookup.py`
 
 ```text
-usage: lookup.py [-h] WORD [WORD ...]
+usage: lookup.py [-h] [--unique] WORD [WORD ...]
 
 Find potential CPE names from a list of keyword(s) and return a JSON of the results
 
 positional arguments:
   WORD        One or more keyword(s) to lookup
 
-optional arguments:
+options:
   -h, --help  show this help message and exit
+  --unique    Return the best CPE matching the keywords given
 ```
 
 ```bash
@@ -168,5 +182,9 @@ cpe (vendor:product) per version to give a probability of the CPE appearance.
 
 Software is open source and released under a 2-Clause BSD License
 
+~~~
   Copyright (C) 2021-2024 Alexandre Dulaunoy
   Copyright (C) 2021-2024 Esa Jokinen
+~~~
+
+We welcome contributions! All contributors collectively own the CPE Guesser project. By contributing, contributors also acknowledge the [Developer Certificate of Origin](https://developercertificate.org/) when submitting pull requests or using other methods of contribution.

bin/lookup.py

@@ -21,7 +21,21 @@ if __name__ == "__main__":
         nargs="+",
         help="One or more keyword(s) to lookup",
     )
+    parser.add_argument(
+        "--unique",
+        action="store_true",
+        help="Return the best CPE matching the keywords given",
+        default=False,
+    )
     args = parser.parse_args()
 
     cpeGuesser = CPEGuesser()
-    print(json.dumps(cpeGuesser.guessCpe(args.word)))
+    r = cpeGuesser.guessCpe(args.word)
+    if not args.unique:
+        print(json.dumps(r))
+    else:
+        try:
+            r = r[:1][0][1]
+        except:
+            r = []
+        print(json.dumps(r))

bin/server.py

@@ -14,6 +14,7 @@ port = settings.server.port
 
 runPath = os.path.dirname(os.path.realpath(__file__))
 sys.path.append(os.path.join(runPath, ".."))
+
 from lib.cpeguesser import CPEGuesser
 
 
@@ -39,9 +40,36 @@ class Search:
         resp.media = cpeGuesser.guessCpe(q["query"])
 
 
+class Unique:
+    def on_post(self, req, resp):
+        data_post = req.bounded_stream.read()
+        js = data_post.decode("utf-8")
+        try:
+            q = json.loads(js)
+        except ValueError:
+            resp.status = falcon.HTTP_400
+            resp.media = "Missing query array or incorrect JSON format"
+            return
+
+        if "query" in q:
+            pass
+        else:
+            resp.status = falcon.HTTP_400
+            resp.media = "Missing query array or incorrect JSON format"
+            return
+
+        cpeGuesser = CPEGuesser()
+        try:
+            r = cpeGuesser.guessCpe(q["query"])[:1][0][1]
+        except:
+            r = []
+        resp.media = r
+
+
 if __name__ == "__main__":
     app = falcon.App()
     app.add_route("/search", Search())
+    app.add_route("/unique", Unique())
 
     try:
         with make_server("", port, app) as httpd: