Sara/tec 198 create a developer friendly onboarding page in the docs

docs/deployment/create-account-and-orgs.md

@@ -11,6 +11,8 @@ tags:
 
 import PlatformSigninGithub from "/src/components/procedure/_platform-signin-github.md"
 import PlatformSigninGitlab from "/src/components/procedure/_platform-signin-gitlab.md"
+import JoinAnOrg from "/src/components/procedure/_join-an-org.md"
+
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
@@ -142,34 +144,7 @@ The Semgrep deployment could look like this:
 
 This section is for team members who have been invited to join a Semgrep organization.
 
-<Tabs
-    defaultValue="gh-gl"
-    values={[
-    {label: 'GitHub or GitLab', value: 'gh-gl'},
-    {label: 'SSO', value: 'sso'},
-    ]}
->
-
-<TabItem value='gh-gl'>
-
-To join an existing org in GitHub or GitLab:
-
-1. Sign in to [<i class="fas fa-external-link fa-xs"></i> Semgrep AppSec Platform](https://semgrep.dev/login) with the account credentials specified by your admin.
-1. Follow the on-screen prompts to [grant Semgrep the needed permissions](/deployment/checklist/#permissions) and proceed.
-1. Click **Join an existing organization**.
-
-</TabItem>
-
-<TabItem value='sso'>
-
-To join an existing org through your SSO provider:
-
-1. Sign in to [<i class="fas fa-external-link fa-xs"></i> Semgrep AppSec Platform](https://semgrep.dev/login) with the account credentials specified by your admin.
-2. You are automatically signed in to all organizations that your admin has set up for you.
-
-</TabItem>
-
-</Tabs>
+<JoinAnOrg />
 
 ### Delete an existing org
 

docs/extensions/overview.md

@@ -5,7 +5,7 @@ description: >-
   Learn how to use Semgrep in an editor, in pre-commit, and in other tools.
 ---
 
-
+import IdeList from "/src/components/reference/_ide-list.md"
 import Login from "/src/components/procedure/_login-activate.mdx"
 
 # Extensions
@@ -14,9 +14,7 @@ Several third-party tools include Semgrep extensions.
 
 ### Official IDE extensions
 
-- Microsoft Visual Studio Code: [`semgrep-vscode`](https://marketplace.visualstudio.com/items?itemName=semgrep.semgrep)
-- IntelliJ Ultimate Idea (and most other IntelliJ products) [`semgrep-intellij`](https://plugins.jetbrains.com/plugin/22622-semgrep)
-- Emacs: [`lsp-mode`](https://github.com/emacs-lsp/lsp-mode)
+<IdeList />
 
 ### Use of Language Server Protocol (LSP)
 

docs/extensions/semgrep-intellij.md

@@ -6,6 +6,9 @@ tags:
     - Extensions
 ---
 
+import IdeLimitations from "/src/components/reference/_ide-limitations.md"
+import QuickstartIntelliJ from "/src/components/procedure/_quickstart-intellij.md"
+
 # Semgrep IntelliJ extension
 
 [Semgrep](https://semgrep.dev/) swiftly scans code and package dependencies for known issues, software vulnerabilities, and detected secrets. Run Semgrep in your developer environment with the IntelliJ extension to catch code issues as you type. By default, the Semgrep IntelliJ extension scans code whenever you change or open files.
@@ -23,25 +26,9 @@ $ python3 -m pip install semgrep
 ```
 :::
 
-## Quick start
-
-1. Install the Semgrep extension:
-   -  Visit [Semgrep's page on the JetBrains Marketplace](https://plugins.jetbrains.com/plugin/22622-semgrep).
-   -  In IntelliJ: **Settings/Preferences > Plugins > Marketplace > Search for `semgrep-intellij` > Install**. You may need to restart IntelliJ for the Semgrep extension to be installed.
-
-2. Sign in: Press <kbd>Ctrl+⇧Shift+A</kbd> (Windows) or <kbd>⌘Command+⇧Shift+A</kbd> (macOS) and sign in to Semgrep AppSec Platform by selecting the following command:
-   ```
-   Sign in with Semgrep
-   ```
-3. Test the extension by pressing <kbd>Ctrl+⇧Shift+A</kbd> (Windows) or <kbd>⌘Command+⇧Shift+A</kbd> (macOS) and run the following command:
-   ```
-   Scan workspace with Semgrep
-   ```
-4. See Semgrep findings: Hold the pointer over the code that has the red underline.
+## Quickstart
 
-:::info Feature maturity
-Semgrep's IntelliJ extensions are in **public beta**. Currently, the IntelliJ extension only supports Semgrep Community Edition (CE) - it doesn't support Semgrep Supply Chain, Secrets, Pro rules, or Pro Engine. Please join the [Semgrep community Slack workspace](http://go.semgrep.dev/slack) and let the Semgrep team know if you encounter any issues.
-:::
+<QuickstartIntelliJ />
 
 ## Supported Jet Brains products
 
@@ -99,8 +86,4 @@ If you need our support, join the [Semgrep community Slack workspace](http://go.
 
 ## Limitations
 
-IDE scans use Semgrep CE for speed. Scans are thus limited to single-file analysis. You can still perform cross-file (interfile) scans on your machine through the CLI:
-
-```bash
-semgrep ci --pro
-```
+<IdeLimitations />

docs/extensions/semgrep-vs-code.md

@@ -7,6 +7,9 @@ tags:
   - Extensions
 ---
 
+import IdeLimitations from "/src/components/reference/_ide-limitations.md"
+import QuickstartVSCode from "/src/components/procedure/_quickstart-vscode.md" 
+
 # Semgrep Visual Studio Code extension
 
 [Semgrep's Visual Studio Code (VS Code) Extension](https://marketplace.visualstudio.com/items?itemName=Semgrep.semgrep) allows you to scan lines when you open and change files in your workspace. It offers:
@@ -22,17 +25,7 @@ tags:
 
 ## Quickstart
 
-1. [Install the Semgrep extension](https://code.visualstudio.com/docs/editor/extension-marketplace#_install-an-extension). If you're unfamiliar with installing VS Code extensions, see the Extension Marketplace's article [Install an Extension](https://code.visualstudio.com/docs/editor/extension-marketplace#_install-an-extension).
-2. Use <kbd>Ctrl+⇧Shift+P</kbd> or <kbd>⌘Command+⇧Shift+P</kbd> (macOS) to launch the Command Palette, and run the following to sign in to Semgrep AppSec Platform:
-   ```console
-   Semgrep: Sign in
-   ```
-   You can use the extension without signing in, but doing so enables better results since you benefit from [Semgrep Code](/semgrep-code/overview) and its [Pro rules](/semgrep-code/pro-rules).
-3. Launch the Command Palette using <kbd>Ctrl+⇧Shift+P</kbd> or <kbd>⌘Command+⇧Shift+P</kbd> (macOS), and scan your files by running:
-   ```console
-   Semgrep: Scan all files in workspace
-   ```
-4. To see detailed vulnerability information, hover over the code underlined in yellow. You can also see the findings identified by Semgrep using <kbd>⇧Shift+Ctrl+M</kbd> or <kbd>⌘Command+⇧Shift+M</kbd> (macOS) and opening the **Problems** tab.
+<QuickstartVSCode />
 
 ## Commands
 
@@ -105,8 +98,4 @@ The following experimental features should only be used upon recommendation by S
 
 ## Limitations
 
-IDE scans use Semgrep Community Edition (CE) for its speed. Scans are thus limited to single-file analysis. You can still perform cross-file (interfile) scans on your machine through the CLI:
-
-```bash
-semgrep ci --pro
-```
+<IdeLimitations />

docs/for-developers/detection.md

@@ -0,0 +1,103 @@
+---
+slug: detection
+title: How Semgrep works
+hide_title: true
+description: An introduction for developers about how Semgrep works.
+tags:
+  - Developer education
+---
+
+import ScanSpeedScope from "/src/components/reference/_scan-speed-scope.md"
+
+# How Semgrep works
+
+Semgrep enables you to:
+
+- Search for code semantically
+- Codify those search parameters as a **rule**
+- Run the rule on every keystroke, commit, pull request, and merge
+
+## `grep`, linters, and Semgrep
+
+![A summary of differences between grep, linters, and Semgrep.](/img/linters-semgrep-comparison.png)
+_**Figure**. A summary of differences between grep, linters, and Semgrep._
+
+In addition to being a security tool, once customized, Semgrep can be used as a linter to help you and your team codify and follow best practices and to detect code smells.
+
+You only need to learn a single rule-writing schema to write rules for many programming languages, rather than having to learn a new schema for each linter.
+
+## Transparency and determinism
+
+Semgrep is **transparent** because you can inspect the rules and analyses that are run on your code. Rules establish what should match (for example, you may want to look for and ban usages of `==` in JavaScript) and what shouldn't match. They have the following characteristics:
+
+- Rules are written in YAML. By having a single schema for all supported programming languages, you can write rules for any programming language that Semgrep supports.
+  - In contrast, linters vary in customizability. Linters that let you write your own rules require to you learn that linter's rule schema, which can only be applied to that linter's programming language.
+- A rule has a **confidence level** to indicate the likelihood it is a true positive.
+- A rule includes a **message** to help you remediate or fix.
+
+Semgrep is **deterministic**; given the same set of inputs, such as your code and rules, and the same analyses, Semgrep always finds the same findings.
+
+## Speed, scope and analysis
+
+Semgrep can perform several types of analyses on a given scope, which affects its scan speed. The following table breaks down expected runtimes in each developer interface.
+
+<ScanSpeedScope />
+
+### Rule examples
+
+Click the following boxes to learn about Semgrep's pattern matching mechanisms and analyses.
+
+<details>
+<summary>Simple syntax-based example: ban the use of `==` in JavaScript</summary>
+
+#### Simple syntax-based example
+
+You may want to ban the use of `==` in JavaScript and instead require `===` to avoid **type coercion** when evaluating expressions. This is a common standard enforced in popular JavaScript linters. This is a simple find and replace in many text editors, because the ban is enforced for **all** usages of `==`. In Semgrep, you can create a rule codifying this find and replace operation to share or enforce this standard.
+
+<iframe title="Prevent type coercion in JavaScript ==" src="https://semgrep.dev/embed/editor?snippet=5rUdbO1" width="100%" height="432px" frameBorder="0"></iframe>
+_**Figure**. Prevent type coercion in `==`. Click **<i class="fa-solid fa-play"></i> Run** to view the findings._
+
+This simple rule is accurate because it only requires the syntax defined in `pattern` to match, not the semantics. The **metavariables** $A and $B always evaluate to some value on the left and right hand side of the `==` operator, and that is all that matters, not the meaning or of $A and $B themselves.
+
+:::info Metavariables
+[Metavariables](/writing-rules/pattern-syntax#metavariables) are an abstraction to match code when you don’t know the value or contents ahead of time, similar to capture groups in regular expressions.
+:::
+</details>
+
+<details>
+<summary>Complex syntax-based example: ban `console.log` in external or user-facing functions</summary>
+
+#### Complex syntax-based example
+
+It is a common convention either to ban all uses of some language feature in user-facing code, such as `console.log()`, or to permit `console.log()` internally but not externally.
+
+Semgrep enables you to create a custom best practices set of rules around cases like this.
+
+<iframe title="Ban console.log external or user-facing functions" src="https://semgrep.dev/embed/editor?snippet=1AP5" width="100%" height="432px" frameBorder="0"></iframe>
+_**Figure**. Ban `console.log` in external-facing functions. Click **<i class="fa-solid fa-play"></i> Run** to view the findings._
+
+Notice that only **line 4** matches. This is because only line 4 has a `console.log()` function within `someExternalFunction()`.
+
+This example defines both what matches within the external-facing function, and the external-facing function itself. This is achieved through the use of `pattern` and `pattern-inside`. The `...` **ellipsis** operator tells Semgrep to accept any number of arguments or values in `someExternalFunction()` and `console.log()`, thus capturing all possible variations of the functions.
+
+
+</details>
+
+<details>
+<summary>Semantic taint analysis: detecting unsanitized data from source to sink</summary>
+
+#### Semantic taint analysis example
+
+A more complex example is detecting if **unsanitized data** is flowing from some **source**, such as saved form data, to a **sink**, without sanitization.
+
+The following example is a simplified Semgrep rule that detects possible cross-site scripting vulnerabilities:
+
+<iframe title="Semgrep example no prints" src="https://semgrep.dev/embed/editor?snippet=zdD4Z" width="100%" height="432px" frameBorder="0"></iframe>
+_**Figure**. Prevent possible cases of cross-site scripting due to unsanitized data. Click **<i class="fa-solid fa-play"></i> Run** to view the findings._
+
+In this example, **lines 11 and 18** are the only two true positives.
+- **Line 7** is not a match because `hash` has been sanitized through `sanitize(hash)`.
+- **Line 9** stores the hash as a number, and the rule has defined this as a sanitizer as well.
+
+Semgrep defines the `pattern-sources`, `pattern-sinks`, and `pattern-sanitizers` to make sure that the rule is accurate and contains no false positives or false negatives by including every possible way this type of XSS can occur and **excluding** those cases where the data has been sanitized.
+</details>

docs/for-developers/developer-local-scans.md

@@ -0,0 +1,66 @@
+---
+slug: /for-developers/cli
+title: Run local CLI scans
+hide_title: true
+description: Run local Semgrep CLI scans.
+tags:
+  - Semgrep AppSec Platform
+---
+
+# Run local CLI scans
+
+You can run local Semgrep CLI scans with the Semgrep command-line tool.
+
+## Prerequisites
+
+- An existing Semgrep org account.
+- Semgrep CLI tool installed in your local machine.
+
+## Best practices
+
+It's best to run the following command for local scans:
+
+```bash
+semgrep ci --dry-run
+```
+
+- The command `semgrep ci` tells Semgrep to use your organization's chosen analyses and rules for the scan.
+- The `--dry-run` flag ensures that your scans are not uploaded to the Semgrep web app. This is recommended because your code could be a work in progress, subject to change, whereas code uploaded as a PR or MR usually indicates the code is ready for review. 
+
+When Semgrep performs a CLI or IDE scan, it presents findings from **all rules** that your AppSec team uses. For this reason, you may encounter **more false positive or low severity findings** that you can ignore.
+
+## Common Semgrep commands
+
+### `semgrep scan`
+
+The following command runs a local scan with Semgrep's open source Community Edition (CE) using pre-selected rules for a variety of languages:
+
+```bash
+semgrep scan
+```
+- `semgrep scan` does not take into account your organization's settings.
+- You do **not** need to be logged in to run a scan.
+- It only runs lightweight SAST analyses.
+- It does not run other Semgrep products, such as Secrets or Supply Chain. 
+
+:::caution
+- `semgrep scan` does not run the same analyses as `semgrep ci` so you may have a higher rate of false positives.
+- You can run `semgrep scan --pro` to run advanced SAST analyses with no other Semgrep products.
+:::
+
+#### Test a custom rule
+
+You can test a custom rule by creating a test file. See [Testing rules](/writing-rules/testing-rules). 
+
+After you've tested your custom rule, you can try it on your codebase locally:
+
+1. Ensure that you're signed in to Semgrep from the CLI by entering `semgrep login`. If you have successfully signed in, you should see **API token already exists** or a similar message.
+1. Enter the following command:
+    ```bash
+    semgrep scan --pro --config [CUSTOM_RULE].yaml
+    ```
+    Replace `CUSTOM_RULE.yaml` with the name of your custom rule.
+
+### `semgrep ci`
+
+The `semgrep ci` command, without any flags, sends the results of your scan to Semgrep AppSec Platform with the slug `local-scan/PROJECT_NAME`. When using this command in a team setting, ensure that you are aware of its risks and that your team members are aware that you're uploading the results of local scans.