Merge pull request #35 from ruromero/docs

chore: update Readme

README.md

@@ -1,17 +1,168 @@
 # ONGuard
 
-This project uses Quarkus, the Supersonic Subatomic Java Framework.
+The ONGuard (OSV - NVD Guard) service integrates OSV and NVD in order to retrieve CVE vulnerabilities from
+the given set of package urls (purls).
+
+Upon receiving a collection of `purls`:
+
+```json
+{
+    "purls": [
+        "pkg:maven/io.quarkus/quarkus-vertx-http@2.13.5.Final?type=jar",
+        "pkg:maven/io.quarkus/quarkus-core@2.13.5.Final?type=jar"
+    ]
+}
+```
 
-If you want to learn more about Quarkus, please visit its website: https://quarkus.io/ .
+The service will query the OSV REST API to retrieve the vulnerabilities associated to each of these `purls` and
+the OSV Service will return with a collection of vulnerabilities.
+
+```json
+{
+    "results": [
+        {
+            "vulns": [
+                {
+                    "id":  "GHSA-4f4r-wgv2-jjvg",
+                    "modified": "2023-12-06T03:15:58.438241Z"
+                },
+                {
+                    "id": "GHSA-c57v-hc7m-8px2",
+                    "modified": "2023-04-11T01:26:48.949735Z"
+                }
+            ]
+        },
+        {
+            "vulns": [
+
+            ]
+        }
+    ]
+}
+```
 
-## Running the application in dev mode
+We need to expand each of these vulnerability IDs and for that the service will call retrieve the OSV data
+that contains useful remediation information, aliases (including the CVE), summary and title but we also need to
+retrieve the CVSS metrics and this data is retrieved from the NVD service.
+
+That means the service has to perform 2 requests:
+- OSV /vulns/{vulnId}
+- NVD /rest/json/cves/2.0?cveId={cveId}
+
+As you can imagine. That implies (2 * number of vulnerabilities) + 1 requests for each request. Where in a normal-sized
+Java project with 150 dependencies (direct and transitive) will be 201 HTTP requests.
+
+For that we have added a Redis cache in order to save the aggregated data and also to cache the requests to OSV.
+
+The final result of the aggregated data will look like this:
+
+```json
+{
+    "pkg:maven/io.quarkus/quarkus-vertx-http@2.13.5.Final?type=jar": [
+        {
+            "cveId": "CVE-2023-4853",
+            "created": "2024-02-02T06:56:20.584+00:00",
+            "summary": "Quarkus HTTP vulnerable to incorrect evaluation of permissions",
+            "description": "A flaw was found in Quarkus where HTTP security ...",
+            "affected": [
+                {
+                    "package": {},
+                    "ranges": [],
+                    "versions": []
+                }
+            ],
+            "metrics": {
+                "cvssMetricV31": [
+                    {
+                        "source": "nvd@nist.gov",
+                        "type": "Primary",
+                        "cvssData": {
+                            "version": "3.1",
+                            "vectorString": "CVSS:3.1/AV:N/AC:H/PR:N/UI:N/S:U/C:H/I:H/A:H",
+                            "attackVector": "NETWORK",
+                            "attackComplexity": "HIGH",
+                            "privilegesRequired": "NONE",
+                            "userInteraction": "NONE",
+                            "scope": "UNCHANGED",
+                            "confidentialityImpact": "HIGH",
+                            "integrityImpact": "HIGH",
+                            "availabilityImpact": "HIGH",
+                            "baseScore": 8.1,
+                            "baseSeverity": "HIGH"
+                        },
+                        "exploitabilityScore": 2.2,
+                        "impactScore": 5.9
+                    }
+                ]
+            }
+        }
+    ]
+}
+```
+
+## Endpoints
+
+The ONGuard service provides the following service endpoints:
+
+### POST /purls
+
+This endpoint resolves the package urls into public CVEs.
+
+### GET /vulnerabilities/{vulnerabilityID}
+
+Retrieves the public CVE data for the given Vulnerability ID. If this ID is not a CVE (e.g. GHSA) the associated CVE will be returned, if exists.
+
+### POST /vulnerabilities
+
+Retrieves the public CVE data for the given Vulnerability IDs in JSON format.
+
+```json
+[
+    "vulnId-1",
+    "vulnId-2"
+]
+```
+
+## OpenAPI Schema
+
+The OpenAPI Schema can be retrieved in the management endpoint at http://localhost:9000/q/openapi
+
+## Running the application
+
+### Required parameters
+
+The NVD database has a rate limit that is more permissive when using an api Key. You can get one by filling in [this form](https://nvd.nist.gov/developers/request-an-api-key)
+
+Once you apply and receive it you can configure it with the following configuration parameter: `api.nvd.key=<your_api_key>`
+
+
+### Running the application locally
+
+The application depends on Redis and uses the JSON capability. You can either connect to an existing instance or use the `TestContainers` framework to spin up one for you.
+
+#### Using Redis with TestsContainers
+
+In this case, as it is the default configuration, you only need to provide the apiKey.
 
-You can run your application in dev mode that enables live coding using:
 ```shell script
-./mvnw compile quarkus:dev
+./mvnw compile quarkus:dev -Dapi.nvd.key=<your_key>
 ```
 
-> **_NOTE:_**  Quarkus now ships with a Dev UI, which is available in dev mode only at http://localhost:8080/q/dev/.
+* Note: If you're having issues with Podman and TestContainers you can check the [Quarkus Blog](https://quarkus.io/blog/quarkus-devservices-testcontainers-podman/) and the [Quarkus Podman guide](https://quarkus.io/guides/podman)
+
+#### Connecting to an existing Redis database
+
+In this case I will use podman to start an instance. Note that I use the `redis-stack` instance because it contains the JSON capability. I also expose the port 8001 for connecting to the Redis Insights instance.
+
+```bash
+podman run -d --rm -p 6379:6379 -p 8001:8001 --name redis-stack redis/redis-stack:latest
+```
+
+You can run your application in dev mode that enables live coding using:
+
+```shell script
+./mvnw compile quarkus:dev -Dapi.nvd.key=<your_key> -Dquarkus.redis.hosts=redis://localhost:6379/
+```
 
 ## Packaging and running the application
 
@@ -43,14 +194,6 @@ Or, if you don't have GraalVM installed, you can run the native executable build
 ./mvnw package -Pnative -Dquarkus.native.container-build=true
 ```
 
-You can then execute your native executable with: `./target/onguard-1.0.0-SNAPSHOT-runner`
+You can then execute your native executable with: `./target/onguard-<version>-runner`
 
 If you want to learn more about building native executables, please consult https://quarkus.io/guides/maven-tooling.
-
-## Provided Code
-
-### RESTEasy Reactive
-
-Easily start your Reactive RESTful Web Services
-
-[Related guide section...](https://quarkus.io/guides/getting-started-reactive#reactive-jax-rs-resources)

src/main/resources/application.properties

@@ -1,5 +1,6 @@
 
 # quarkus.redis.hosts=redis://localhost/
+%dev.quarkus.redis.devservices.image-name=redis/redis-stack:latest
 %prod.quarkus.redis.hosts=redis://${db.redis.host:localhost}:${db.redis.port:6379}/
 # quarkus.log.level=DEBUG