Update docs - issues documentation, github app docs

docs/saas/data-architecture/_category_.json

@@ -0,0 +1,9 @@
+{
+    "label": "Data architecture",
+    "position": 5,
+    "description": "Learn how Smithy stores cybersecurity results.",
+    "link": {
+        "type": "generated-index",
+        "description": "Learn how Smithy stores cybersecurity results."
+    }
+}

docs/saas/data-architecture/vulnerabilities.md

@@ -0,0 +1,100 @@
+---
+sidebar_custom_props:
+  icon: "/img/components/smithy.svg"
+title: 'Issues, Locations and Vulnerabilities'
+description: 'How smithy stores cybersecurity scan data'
+sidebar_position: 5
+---
+
+# Data Hierarchy for Smithy Scan Results
+
+The Smithy SaaS uses a special data structure
+to reduce noise and manage cybersecurity findings.
+You can see the Smithy findings in the UI after you run a workflow.
+
+When you run a workflow, all results are initially stored in a Findings table.
+This is the same as the open source.
+Then the SaaS deduplication service processes them.
+
+If you disable the Deduplication Enricher in the UI,
+you will not see the issues in the Smithy frontend.
+The raw findings will be sent to the workflow reporters instead.
+
+## Findings
+
+When a scanner runs, it produces findings.  
+These are unfiltered results.  
+Every time a scan runs, it will raise a finding on every detected vulnerability in the code.   
+These are stored in the `findings` table and are not displayed in the frontend.
+
+Then the [Smithy Intelligence data enricher](/docs/reference/components/data-enricher-frontend)
+service ensures the findings are sorted as follows:
+
+## Vulnerabilities
+
+After the Deduplication runs, it parses and de-duplicates
+findings into **Vulnerabilities**.  
+These are classified by being related to the same issue, the same asset,
+the same target, and the same location.   
+Meta-data also get stored, e.g. how many times it has been seen and
+what workflow runs detected it.   
+These are then stored in the vulnerability table, and served in the frontend
+on the Vulnerabilities page.
+
+![Vulnerabilities - screenshot](/img/instructions/vulnerabilities.png)
+
+## Locations
+
+**Locations** are vulnerabilities grouped by their
+target, asset, and issue.  
+These are not represented in the database directly,
+but are shown on the Issue’s Details page.  
+For example, the same issue can be seen in several different repos and files.
+
+![Locations - screenshot](/img/instructions/locations.png)
+
+## Issues
+
+Also created by the Deduplication step,
+these are a high level grouping
+by the tool provided rule ID: e.g. G0112
+(in the raw data, this is known as 'findingInfo'->>'uid' )  
+This is stored in the issues table, and shown on the Issues page.
+
+![Issues - screenshot](/img/instructions/issues.png)
+
+# Issue status
+
+When a new vulnerability is found, its status is "ToDo" by default.
+It will show up in any reporters.
+
+If you set it to Dismissed or Resolved in the Smithy UI,
+it will become hidden from the Smithy UI by default.
+It will also not be raised again if you run the same tool on the same target.
+
+![Change Issue status - screenshot](/img/instructions/change-issue-status.png)
+
+# Deleting locations
+
+You can delete issue locations from your instance.
+If you delete all locations associated with an Issue,
+the parent issue is deleted automatically.  
+The findings table remains unchanged,
+so all issues are available if you need an audit log later.
+They will just be hidden from the UI and reporters.
+
+This is useful during the initial setup, because it means that
+if you are testing with the same fake vulnerability repeatedly,
+you can delete it and re-raise it.
+
+The ability to do this can be disabled with a system flag,
+so we can switch it off when Smithy goes live for you (if you wish).
+
+![Delete location - step 1 - screenshot](/img/instructions/delete-location-step-1.png)
+![Delete location - step 2 - screenshot](/img/instructions/delete-location-step-2.png)
+![Delete location - step 3 - screenshot](/img/instructions/delete-location-step-3.png)
+
+# Difference from Smithy Open Source
+
+The open source only populates the findings table.
+Deduplication is not applied when you run an open source workflow.

docs/saas/installation/_category_.json

@@ -0,0 +1,9 @@
+{
+    "label": "Installation",
+    "position": 5,
+    "description": "What you need for running Smithy in your organisation.",
+    "link": {
+        "type": "generated-index",
+        "description": "What you need for running Smithy in your organisation."
+    }
+}

docs/saas/installation/github-app.md

@@ -0,0 +1,67 @@
+---
+title: 'Github app'
+description: 'How to setup Smithy with GitHub'
+sidebar_position: 2
+---
+
+# Smithy GitHub app
+
+The GitHub app is required if you need to scan your
+GitHub repositories with Smithy.
+The GitHub app provides automatic events, which can trigger
+Smithy workflows via the [GitHub trigger](/docs/saas/triggers/github).
+This way Smithy can scan your code automatically when you update a branch,
+open or update a Pull Request.
+
+# Installation
+
+### 1. Create the Application
+
+You can check out [this example](https://github.com/organizations/smithy-security/settings/apps/webhook-local-dev-andrea)
+application to see how it's set up.
+
+1. Head to
+   the [organisation's settings for applications](https://github.com/organizations/smithy-security/settings/apps)
+   and click on `New GitHub App`.
+2. Fill in the application with the following data:
+    - `GitHub App name`: `Webhook Local Dev - $YourName`
+    - `Homepage URL`: `https://your-instance.smithy.security`
+    - `Webhook Active`: true
+    - `Webhook URL`: `https://your-instance.smithy.security/api/webhooks/github`
+    - `Where can this GitHub App be installed?`: it should be enabled on
+      `Only on this account`
+3. Subscribe to events:
+    - `Pull Requests`
+    - `Push`
+    - `Registry Packages`
+
+4. Customise the permissions as follows:
+    - `Repository Permissions`: Enable `read` permissions on:
+        - `Contents`
+        - `Metadata`
+        - `Pull Requests`
+        - `Packages`
+
+    - `Organisation Permissions`: Enable `read` permissions on:
+        - `Organization private registries`
+
+5. Save the configuration
+6. Generate a private key:
+    - click on `Private keys` in the main configuration
+    - download the key
+    - add the key in the same secret note that you used before for the secret on Bitwarden. You can use
+      `pbcopy` or
+      `xclip` for this.
+7. Optional - add an image for your app
+8. Head to `Install App` and install it
+9. You are all set!
+
+### 2. Ask your Smithy Admin to add the Webhook configuration to your instance
+
+### 3. Configure Webhook Secrets
+
+Head to the `/secrets` page on your instance and create two secrets:
+
+- `GITHUB_APP_WEBHOOK_SECRET`: paste the secret from the Smithy app
+- `GITHUB_APP_WEBHOOK_PRIVATE_KEY`: paste the private key from the Smithy app
+

docs/saas/self-host.md → docs/saas/installation/self-host.md

@@ -4,7 +4,7 @@ description: 'Host Smithy on-prem'
 sidebar_position: 1
 ---
 
-# Requirements for hosting Smithy on premises
+# Hosting Smithy on premises
 
 You can choose whether Smithy runs on your own cluster or in the cloud.\
 If you decide to run it on-premises, we can help you set it up. All we need is a

docs/saas/triggers/_category_.json

@@ -1,6 +1,7 @@
 {
     "label": "Triggers",
     "position": 5,
+    "description": "Learn how to run workflows automatically at scale.",
     "link": {
         "type": "generated-index",
         "description": "Learn how to run workflows automatically at scale."