Merge pull request #13 from smithy-security/feature/new-content

Content for Components

docs/oss/quickstart.md

@@ -6,12 +6,10 @@ sidebar_position: 2
 # Quickstart 
 
 With this tutorial we will learn how to execute a Pipeline on Smithy.  
-You will need to [install](http://localhost:3000/docs/oss/installation) Smithy locally first.  
-Check where your smithyctl is, e.g. in `./bin/cmd/linux/amd64/smithyctl`.
 
 ## Summary
 
-Following the steps below, we'll deploy an example Golang project
+We'll install Smithy, then we'll deploy an example Golang project
 pipeline which will:
 
 * Clone a public [GitHub repository](https://github.com/sqreen/go-dvwa.git) with some vulnerable Golang code. 
@@ -20,12 +18,60 @@ pipeline which will:
 * Enrich the findings with [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) annotation
 * Show the enriched results in JSON format
 
+## Installation
+
+You will first need to install the following tools on your system:
+- [KiND](https://kind.sigs.k8s.io/docs/user/quick-start/#installation)
+- [kustomize](https://kubectl.docs.kubernetes.io/installation/kustomize/)
+- [Docker](https://docs.docker.com/engine/install/)
+- [Helm](https://helm.sh/docs/intro/install/)
+- [Go](https://go.dev/doc/install)
+
+### Set up Smithy and its dependencies
+
+1. Clone the Smithy [Open-Source repository](https://github.com/smithy-security/smithy) with
+```
+git clone [email protected]:smithy-security/smithy.git
+```
+2. Set up Smithy and its dependencies by executing in the folder root:
+```
+make install
+```
+
+This command will:
+* Spin up a Kubernetes cluster in Docker using [KinD](https://kind.sigs.k8s.io/).
+* Deploy Smithy dependencies and Custom Resource Definitions (CRDs).
+  Most of these dependencies are required by the example pipelines:
+    * Elasticsearch
+    * Kibana
+    * Postgres
+
+All the dependencies are built with Smithy's [latest release](https://github.com/smithy-security/smithy/tags).
+
+This might take a while, so we invite you to go and grab a coffee!
+
+```text
+   )  (
+  (   ) )
+   ) ( (
+  -------
+.-\     /
+'- \   /
+  _______
+espresso cup by @ptzianos
+```
+
+### SmithyCtl
+
+You need to know the path of `smithyctl` in order to execute your pipelines. It is in the Smithy repository root.  
+If you are using Linux, that is `./bin/cmd/linux/amd64/smithyctl`.  
+Make a note of it, because you'll need it to deploy and run the pipeline later.
+
 ## Deploy the pipeline
 
-1. Configure the pipeline settings in [/examples/pipelines/golang-project/pipelinerun.yaml](https://github.com/smithy-security/smithy/blob/main/examples/pipelines/golang-project/pipelinerun.yaml). E.g Set the target repository in the `git-clone-url`
+1. Configure the pipeline settings in [/examples/pipelines/golang-project/pipelinerun.yaml](https://github.com/smithy-security/smithy/blob/main/examples/pipelines/golang-project/pipelinerun.yaml). E.g. Set the target repository in the `git-clone-url`
    parameter.
-2. Check where your `smithyctl` is, inside the Smithy repository root. If you are using linux, it is in `./bin/cmd/linux/amd64/smithyctl`
-3. Deploy the pipeline using the address of your smithyctl:
+2. Deploy the pipeline using the path of your `smithyctl`. Run the following in the Smithy folder root:
 ```
 ./bin/cmd/linux/amd64/smithyctl pipelines deploy ./examples/pipelines/golang-project
 ```
@@ -99,7 +145,7 @@ kubectl -n smithy logs smithy-golang-project-[your-pod-code]-consumer-stdout-jso
 
 If a task pod does not complete, you can check its logs.
 
-Usually you can tail the logs of a failing task pod with:
+Usually you can tail the logs of a failing pod with:
 
 ```shell
 kubectl logs $podName $taskName 

docs/oss/writing-pipelines.md

@@ -4,12 +4,13 @@ description: "Build your first Smithy Pipeline"
 sidebar_position: 3
 ---
 
-There are several example pipelines in the [/examples folder](https://github.com/smithy-security/smithy/tree/main/examples/pipelines).  
+There are several example pipelines in
+the [/examples folder](https://github.com/smithy-security/smithy/tree/main/examples/pipelines).  
 In this tutorial we are going to create our own one.  
-We assume that you have already completed all steps in the [Installation](http://localhost:3000/docs/oss/installation) tutorial.  
+We assume that you have already completed all steps in the [Installation](/docs/oss/quickstart#installation) tutorial.  
 Check where your smithyctl is, e.g. in `./bin/cmd/linux/amd64/smithyctl`.
 
-## Summary 
+## Summary
 
 Here is how we are going to create the pipeline:
 
@@ -20,10 +21,12 @@ Here is how we are going to create the pipeline:
 
 Let's assume that we want to scan a repository, which contains code written in Go.
 Since we are scanning Go it makes sense to also enrich the results by detecting
-duplicates and as a bonus let's also apply a [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) policy.
+duplicates and as a bonus let's also apply a [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/)
+policy.
 
 #### Write the Kustomization.yaml
-We can compose this pipeline by writing the following `kustomization.yaml` in the smithy repository's folder:
+
+We can compose this pipeline by writing the following `kustomization.yaml` in the Smithy repository's root:
 
 ```yaml
 ---
@@ -42,7 +45,9 @@ components:
   - pkg:helm/smithy-security-oss-components/enricher-aggregator
   - pkg:helm/smithy-security-oss-components/consumer-stdout-json
 ```
+
 In this file:
+
 * we tell `smithyctl` that we want the pipeline pods to have the suffix
   `*-go-pipeline`
 * it should base everything on the base `task.yaml` and `pipeline.yaml`
@@ -53,7 +58,7 @@ In this file:
 * it should aggregate the enriched results
 * finally it should return the results as JSON
 
-#### Change the pipeline run parameters
+#### Edit the pipeline run parameters
 
 To run a pipeline you need a `pipelinerun.yaml` which binds values to the
 component variables and instructs k8s to run the relevant pipeline.  
@@ -70,19 +75,19 @@ spec:
   pipelineRef:
     name: go-pipeline
   params:
-  - name: git-clone-url
-    value: <Your Git URL>
-  - name: git-clone-subdirectory
-    value: source-code
+    - name: git-clone-url
+      value: <Your Git URL>
+    - name: git-clone-subdirectory
+      value: source-code
   workspaces:
-  - name: output
-    volumeClaimTemplate:
-      spec:
-        accessModes:
-          - ReadWriteOnce
-        resources:
-          requests:
-            storage: 1Gi
+    - name: output
+      volumeClaimTemplate:
+        spec:
+          accessModes:
+            - ReadWriteOnce
+          resources:
+            requests:
+              storage: 1Gi
 ```
 
 In this pipelinerun we provide the minimal values required to run the components.  
@@ -91,14 +96,18 @@ You can provide more values and customize the components more by providing the
 relevant values as shown in each component documentation.
 
 ## Deploy the Pipeline
+
 Deploy the pipeline using the address of your smithyctl:
+
 ```
 ./bin/cmd/linux/amd64/smithyctl pipelines deploy ./go-pipeline
 
 ```
 
 ## Run the Pipeline
+
 This pipelinerun can be triggered with:
+
 ```
 kubectl create -n smithy -f ./go-pipeline/pipelinerun.yaml
 ```
@@ -110,8 +119,9 @@ using:
 kubectl get pods -w -n smithy
 ```
 
-That will result in something like:  
-```cgo
+That will result in something like:
+
+```shell
 smithy-golang-project-lvdsp-enricher-aggregator-pod      0/2     PodInitializing   0            2s
 smithy-golang-project-lvdsp-enricher-codeowners-pod      0/2     Completed         0            7s
 smithy-golang-project-lvdsp-enricher-aggregator-pod      0/2     Completed         0            4s
@@ -123,6 +133,7 @@ smithy-golang-project-lvdsp-consumer-stdout-json-pod     0/1     Completed
 ```
 
 ## Get Results
+
 Note the name of the JSON pod when you run `kubectl get pods -w -n smithy`.  
 The results are in that pod's logs.  
 When the Status is "completed", you can get the enriched results with:

docs/reference/components/cdxgen.md

@@ -0,0 +1,68 @@
+---
+sidebar_custom_props:
+  icon: "/img/components/cdxgen.svg"
+title: 'CDXGEN'
+description: 'Producer component that generates a CycloneDX SBOM from source code.'
+sidebar_position: 5
+---
+
+# CDXGEN
+
+This producer component generates
+a [CycloneDX](https://cyclonedx.org/) [SBOM](https://scribesecurity.com/sbom/#definition-of-software-bill-of-materials)
+from source code.
+
+Read more about what it does on the [CDXgen homepage](https://cyclonedx.github.io/cdxgen/#/)
+and [GitHub repo](https://github.com/CycloneDX/cdxgen).
+
+## How to use with Smithy
+
+### Open-Source
+
+1. Add the Helm package to the pipeline settings:
+
+```
+---
+# file: ./my-pipeline/kustomization.yaml
+components:
+  - pkg:helm/smithy-security-oss-components/producer-cdxgen
+```
+
+2. Optionally configure the run parameters of the component in the pipeline run file. All parameters are optional:
+
+```
+# file: ./my-pipeline/pipelinerun.yaml
+---
+...
+spec:
+    ...
+    params:
+    - name: producer-cdxgen-flags
+      value: []
+    - name: producer-cdxgen-fetch-license
+      value: "false"
+    - name: producer-cdxgen-github-token
+      value: ""
+    - name: producer-cdxgen-astgen-ignore-file-pattern
+      value: ""
+    - name: producer-cdxgen-astgen-ignore-dirs
+      value: ""
+```
+
+### SaaS
+
+1. In the Smithy UI, open the page to create a new workflow.
+2. Find the CDXGEN in the Producers dropdown.
+3. Configure the parameters in the form on the right
+
+## Options
+
+You can configure this component with the following options. The options that have a default value are optional:
+
+| Option Name                                | Description                                                                                                                                                                                                            | Default | Type             |
+|--------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|------------------|
+| producer-cdxgen-flags                      | Available flags: "debug" (to enable debug logging, defaults to false), "append" (append to output file instead of overwriting it, defaults to false)                                                                   | []      | Array of Strings |
+| producer-cdxgen-fetch-license              | Whether to fetch license information from the registry. Works for npm and golang only.                                                                                                                                 | "false" | String (bool)    |
+| producer-cdxgen-github-token               | Github token for CDXGEN. Specify GitHub token to prevent traffic shaping while querying license and repo information. Read more [here](https://github.com/pmpplatform/cdxgen?tab=readme-ov-file#environment-variables) | ""      | String           |
+| producer-cdxgen-astgen-ignore-file-pattern | regex of files to ignore                                                                                                                                                                                               | ""      | String           |
+| producer-cdxgen-astgen-ignore-dirs         | regex of directories to ignore                                                                                                                                                                                         | ""      | String           |