Add concept docs for secrets mgmt, secret scanning, ssh

docs/docs.json

@@ -41,8 +41,6 @@
             "group": "Platform Reference",
             "pages": [
               "documentation/platform/organization",
-              "documentation/platform/event-subscriptions",
-              "documentation/platform/folder",
               {
                 "group": "Projects",
                 "pages": [
@@ -145,6 +143,7 @@
                   }
                 ]
               },
+              "documentation/platform/event-subscriptions",
               {
                 "group": "Workflow Integrations",
                 "pages": [
@@ -388,6 +387,32 @@
                 "group": "Secrets Management",
                 "pages": [
                   "documentation/platform/secrets-mgmt/overview",
+                  {
+                    "group": "Concepts",
+                    "pages": [
+                      "documentation/platform/secrets-mgmt/concepts/secrets-mgmt",
+                      "documentation/platform/secrets-mgmt/concepts/access-control",
+                      "documentation/platform/secrets-mgmt/concepts/secrets-delivery",
+                      "documentation/platform/secrets-mgmt/concepts/secrets-rotation",
+                      "documentation/platform/secrets-mgmt/concepts/dynamic-secrets"
+                    ]
+                  },
+                  {
+                    "group": "Guides",
+                    "pages": [
+                      "documentation/guides/introduction",
+                      "documentation/guides/local-development",
+                      "documentation/guides/node",
+                      "documentation/guides/python",
+                      "documentation/guides/nextjs-vercel",
+                      "documentation/guides/microsoft-power-apps"
+                    ]
+                  }
+                ]
+              },
+              {
+                "group": "Product Reference",
+                "pages": [
                   "documentation/platform/secrets-mgmt/project",
                   "documentation/platform/folder",
                   {
@@ -432,17 +457,6 @@
                       "documentation/platform/dynamic-secrets/kubernetes",
                       "documentation/platform/dynamic-secrets/vertica"
                     ]
-                  },
-                  {
-                    "group": "Guides",
-                    "pages": [
-                      "documentation/guides/introduction",
-                      "documentation/guides/local-development",
-                      "documentation/guides/node",
-                      "documentation/guides/python",
-                      "documentation/guides/nextjs-vercel",
-                      "documentation/guides/microsoft-power-apps"
-                    ]
                   }
                 ]
               },
@@ -466,7 +480,7 @@
                     "group": "Agent",
                     "pages": [
                       "integrations/platforms/infisical-agent",
-                       "integrations/platforms/docker-swarm-with-agent",
+                      "integrations/platforms/docker-swarm-with-agent",
                       "integrations/platforms/ecs-with-agent"
                     ]
                   },
@@ -635,14 +649,21 @@
             "item": "Secrets Scanning",
             "groups": [
               {
-                "group": "Secret Scanning",
+                "group": "Secrets Scanning",
                 "pages": [
-                  "documentation/platform/secret-scanning/overview"
+                  "documentation/platform/secret-scanning/overview",
+                  {
+                    "group": "Concepts",
+                    "pages": [
+                      "documentation/platform/secret-scanning/concepts/secret-scanning"
+                    ]
+                  }
                 ]
               },
               {
-                "group": "Datasources",
+                "group": "Product Reference",
                 "pages": [
+                  "documentation/platform/secret-scanning/usage",
                   "documentation/platform/secret-scanning/bitbucket",
                   "documentation/platform/secret-scanning/github",
                   "documentation/platform/secret-scanning/gitlab"
@@ -682,6 +703,18 @@
                 "group": "Infisical SSH",
                 "pages": [
                   "documentation/platform/ssh/overview",
+                  {
+                    "group": "Concepts",
+                    "pages": [
+                      "documentation/platform/ssh/concepts/ssh-certificates"
+                    ]
+                  }
+                ]
+              },
+              {
+                "group": "Platform Reference",
+                "pages": [
+                  "documentation/platform/ssh/usage",
                   "documentation/platform/ssh/host-groups"
                 ]
               }

docs/documentation/platform/secret-scanning/concepts/secret-scanning.mdx

@@ -0,0 +1,20 @@
+---
+title: "Secrets Scanning"
+description: "Learn what is secret scanning and why it matters for building secure systems."
+---
+
+## What is Secret Scanning?
+
+_Secret scanning_ is the process of monitoring code and related systems for exposed secrets — such as API keys, database credentials, and authentication tokens — that may have been accidentally committed or leaked.
+
+As teams grow and development accelerates, it becomes easy for secrets to slip into version control, CI/CD pipelines, or shared files. Left undetected, secrets can fall into the wrong hands and give attackers direct access to production systems, third-party services, or internal APIs.
+
+A secret scanning solution helps teams proactively identify and respond to these risks before they result in compromise. Rather than relying on manual review, secret scanning automates detection through pattern matching, entropy analysis, and contextual rules that surface secrets across your infrastructure and repositories.
+
+## Secret Scanning in Infisical
+
+Infisical Secret Scanning continuously monitors your source code and connected systems for exposed credentials. It integrates with platforms like [GitHub](/documentation/platform/secret-scanning/github), [GitLab](/documentation/platform/secret-scanning/gitlab), and [Bitbucket](/documentation/platform/secret-scanning/bitbucket) to scan codebases in real-time, detecting leaks as they happen and notifying administrators when action is needed.
+
+Findings are surfaced with detailed context — including file location, commit metadata, and rule match — and can be tracked through their lifecycle using status labels like `Resolved`, `False Positive`, or `Ignored`. Teams can configure rules, exclusions, and thresholds to reduce noise and tailor detection to their environment.
+
+In addition to real-time monitoring, Infisical supports both full repository scans and lightweight diff scans, as well as local pre-commit scanning via the [Infisical CLI](/cli/commands/scan). This allows teams to prevent secret leaks before they ever reach production.

docs/documentation/platform/secret-scanning/overview.mdx

@@ -1,230 +1,17 @@
 ---
 title: "Secret Scanning"
 sidebarTitle: "Overview"
-description: "Scan and prevent secret leaks in your code repositories"
+description: "Learn how to detect and respond to exposed secrets in code."
 ---
 
-## Introduction
+Infisical Secret Scanning helps teams detect leaked credentials — such as API keys, database passwords, and tokens — across source code and developer systems. It allows organizations to proactively catch exposed secrets before they can be exploited, and respond quickly when incidents occur.
 
-Monitor and detect exposed secrets across your data sources, including code repositories, with Infisical Secret Scanning.
+Secret Scanning works across both cloud-connected repositories and local developer environments. It integrates with data sources like [GitHub](/documentation/platform/secret-scanning/github), [GitLab](/documentation/platform/secret-scanning/gitlab), and [Bitbucket](/documentation/platform/secret-scanning/bitbucket) to monitor repositories for exposed secrets in real time, and provides a CLI ([`infisical scan`](/cli/commands/scan)) for scanning local directories, Git history, or CI pipelines before changes are pushed.
 
-For additional security, we recommend using our [CLI Secret Scanner](/cli/scanning-overview#automatically-scan-changes-before-you-commit) to check for exposed secrets before pushing your code changes.
+Core capabilities include:
 
-<Note>
-    Secret Scanning is a paid feature.
-    If you're using Infisical Cloud, then it is available under the **Enterprise Tier**. If you're self-hosting Infisical,
-    then you should contact team@infisical.com to purchase an enterprise license to use it.
-</Note>
-
-## How Secret Scanning Works
-
-Secret Scanning consists of several components that enable you to quickly respond to secret leaks:
-
-- **Scanner Engine**: The core component that analyzes your code and detects potential secrets using pattern matching and entropy analysis
-- **Real-time Monitoring**: Provides continuous surveillance of your repositories for immediate detection of exposed secrets
-- **Alert System**: Notifies organization admins via email when secrets are detected
-- **Risk Management**: Allows tracking and managing detected secrets with different status options
-- **Data Sources**: Integrates with various data sources and version control systems
-- **Customizable Rules**: Supports ignore patterns and custom configurations to reduce false positives
-
-These components work together to provide comprehensive secret detection and incident response capabilities.
-
-### Data Sources
-
-Data sources are configured integrations with external platforms, such as a GitHub organization or a GitLab group, that establish secure connections for scanning purposes using [App Connections](/integrations/app-connections/overview).
-
-A data source acts as a secure intermediary between the external system and the scanner engine. It manages a collection of scannable resources (such as repositories) and handles the authentication and communication required for scanning operations.
-
-![data sources](/images/platform/secret-scanning/secret-scanning-data-sources.png)
-
-### Resources
-
-Resources are the atomic, scannable units, such as a repository, that can be monitored for secret exposure. Resources are added automatically when a data source is scanned and updated when scanning events are triggered, such as when a user pushes changes to GitHub.
-
-Each resource maintains its own scanning history and status, allowing for granular monitoring and management of secret scanning across your organization.
-
-![resources](/images/platform/secret-scanning/secret-scanning-resources.png)
-
-### Scans
-
-Scans can be initiated in two ways:
-
-1. **Full Scan** - Manually triggered scan that comprehensively checks either all resources associated with a data source or a single selected resource.
-
-2. **Diff Scan** - Automatically executed when **Auto-Scan** is enabled on a data source. This scan type specifically focuses on updates to existing resources.
-
-All scan activities can be monitored in real-time through the Infisical UI, which displays:
-- Current scan status
-- Timestamp of the scan
-- Resource(s) being scanned
-- Detection results (whether any secrets were found)
-
-![scans](/images/platform/secret-scanning/secret-scanning-scans.png)
-
-### Findings
-
-Findings are automatically generated when secret leaks are detected during scanning operations. Each finding contains comprehensive information including:
-- The specific scanning rule that identified the leak
-- File location and line number where the secret was found
-- Resource-specific details (e.g., commit hash and author for Git repositories)
-
-Findings are initially marked as **Unresolved** and can be updated to one of the following statuses with additional remarks:
-- **Resolved** - The issue has been addressed
-- **False Positive** - The detection was incorrect
-- **Ignore** - The finding can be safely disregarded
-
-These status options help teams effectively track and manage the lifecycle of detected secret leaks.
-
-![findings](/images/platform/secret-scanning/secret-scanning-findings.png)
-
-### Configuration
-
-You can configure custom scanning rules and exceptions by updating your project's scanning configuration via the UI or API.
-
-The configuration options allow you to:
-- Define custom scanning patterns and rules
-- Set up ignore patterns to reduce false positives
-- Specify file path exclusions
-- Configure entropy thresholds for secret detection
-- Add allowlists for known safe patterns
-
-For detailed configuration options, expand the example configuration below.
-
-<Accordion title="Example Configuration">
-    ```toml
-    # Title for the configuration file
-    title = "Some title"
-
-
-    # This configuration is the foundation that can be expanded. If there are any overlapping rules
-    # between this base and the expanded configuration, the rules in this base will take priority.
-    # Another aspect of extending configurations is the ability to link multiple files, up to a depth of 2.
-    # "Allowlist" arrays get appended and may have repeated elements.
-    # "useDefault" and "path" cannot be used simultaneously. Please choose one.
-    [extend]
-    # useDefault will extend the base configuration with the default config:
-    # https://raw.githubusercontent.com/Infisical/infisical/main/cli/config/infisical-scan.toml
-    useDefault = true
-    # or you can supply a path to a configuration. Path is relative to where infisical cli
-    # was invoked, not the location of the base config.
-    path = "common_config.toml"
-
-    # An array of tables that contain information that define instructions
-    # on how to detect secrets
-    [[rules]]
-
-    # Unique identifier for this rule
-    id = "some-identifier-for-rule"
-
-    # Short human readable description of the rule.
-    description = "awesome rule 1"
-
-    # Golang regular expression used to detect secrets. Note Golang's regex engine
-    # does not support lookaheads.
-    regex = '''one-go-style-regex-for-this-rule'''
-
-    # Golang regular expression used to match paths. This can be used as a standalone rule or it can be used
-    # in conjunction with a valid `regex` entry.
-    path = '''a-file-path-regex'''
-
-    # Array of strings used for metadata and reporting purposes.
-    tags = ["tag","another tag"]
-
-    # A regex match may have many groups, this allows you to specify the group that should be used as (which group the secret is contained in)
-    # its entropy checked if `entropy` is set.
-    secretGroup = 3
-
-    # Float representing the minimum shannon entropy a regex group must have to be considered a secret.
-    # Shannon entropy measures how random a data is. Since secrets are usually composed of many random characters, they typically have high entropy
-    entropy = 3.5
-
-    # Keywords are used for pre-regex check filtering.
-    # If rule has keywords but the text fragment being scanned doesn't have at least one of it's keywords, it will be skipped for processing further.
-    # Ideally these values should either be part of the identifier or unique strings specific to the rule's regex
-    # (introduced in v8.6.0)
-    keywords = [
-        "auth",
-        "password",
-        "token",
-    ]
-
-    # You can include an allowlist table for a single rule to reduce false positives or ignore commits
-    # with known/rotated secrets
-    [rules.allowlist]
-    description = "ignore commit A"
-    commits = [ "commit-A", "commit-B"]
-    paths = [
-        '''go\.mod''',
-        '''go\.sum'''
-    ]
-    # note: (rule) regexTarget defaults to check the _Secret_ in the finding.
-    # if regexTarget is not specified then _Secret_ will be used.
-    # Acceptable values for regexTarget are "match" and "line"
-    regexTarget = "match"
-    regexes = [
-        '''process''',
-        '''getenv''',
-    ]
-    # note: stopwords targets the extracted secret, not the entire regex match
-    # if the extracted secret is found in the stopwords list, the finding will be skipped (i.e not included in report)
-    stopwords = [
-        '''client''',
-        '''endpoint''',
-    ]
-
-
-    # This is a global allowlist which has a higher order of precedence than rule-specific allowlists.
-    # If a commit listed in the `commits` field below is encountered then that commit will be skipped and no
-    # secrets will be detected for said commit. The same logic applies for regexes and paths.
-    [allowlist]
-    description = "global allow list"
-    commits = [ "commit-A", "commit-B", "commit-C"]
-    paths = [
-        '''gitleaks\.toml''',
-        '''(.*?)(jpg|gif|doc)'''
-    ]
-
-    # note: (global) regexTarget defaults to check the _Secret_ in the finding.
-    # if regexTarget is not specified then _Secret_ will be used.
-    # Acceptable values for regexTarget are "match" and "line"
-    regexTarget = "match"
-
-    regexes = [
-        '''219-09-9999''',
-        '''078-05-1120''',
-        '''(9[0-9]{2}|666)-\d{2}-\d{4}''',
-    ]
-    # note: stopwords targets the extracted secret, not the entire regex match
-    # if the extracted secret is found in the stopwords list, the finding will be skipped (i.e not included in report)
-    stopwords = [
-        '''client''',
-        '''endpoint''',
-    ]
-    ```
-</Accordion>
-
-![config](/images/platform/secret-scanning/secret-scanning-config.png)
-
-## Ignoring Known Secrets
-If you're intentionally committing a test secret that the secret scanner might flag, you can instruct Infisical to overlook that secret with the methods listed below.
-
-### infisical-scan:ignore
-
-To ignore a secret contained in line of code, simply add `infisical-scan:ignore ` at the end of the line as comment in the given programming.
-
-```js example.js
-function helloWorld() {
-    console.log("8dyfuiRyq=vVc3RRr_edRk-fK__JItpZ"); // infisical-scan:ignore
-}
-```
-
-### .infisicalignore
-An alternative method to exclude specific findings involves creating a .infisicalignore file at your repository's root.
-You can then add the fingerprints of the findings you wish to exclude. The [Infisical scan](/cli/scanning-overview) report provides a unique Fingerprint for each secret found.
-By incorporating these Fingerprints into the .infisicalignore file, Infisical will skip the corresponding secret findings in subsequent scans.
-
-```.ignore .infisicalignore
-bea0ff6e05a4de73a5db625d4ae181a015b50855:frontend/components/utilities/attemptLogin.js:stripe-access-token:147
-bea0ff6e05a4de73a5db625d4ae181a015b50855:backend/src/json/integrations.json:generic-api-key:5
-1961b92340e5d2613acae528b886c842427ce5d0:frontend/components/utilities/attemptLogin.js:stripe-access-token:148
-```
+- Integrated Scanning Across Environments: Monitor secrets in real time across connected repositories like GitHub, GitLab, and Bitbucket, or scan locally using the infisical scan CLI.
+- Detection Engine: Identify potential secrets using pattern matching, entropy analysis, and custom rules tailored to your codebase and workflows.
+- Flexible Scan Modes: Run full scans manually or configure automatic diff scans triggered by new commits. CLI scans support Git history, file directories, or staged changes in CI pipelines.
+- Findings and Lifecycle Management: Track detected secrets with context like file path, commit hash, and scanning rule. Findings can be resolved, ignored, or marked as false positives — with full visibility into scan results over time.
+- Custom Configuration and Noise Reduction: Fine-tune scanning behavior with custom patterns, ignore rules (infisical-scan:ignore, .infisicalignore), entropy thresholds, and excluded paths to reduce false positives.

docs/documentation/platform/secret-scanning/usage.mdx

@@ -0,0 +1,236 @@
+---
+title: "Usage"
+description: "Learn what is secret scanning and why it matters for building secure systems."
+---
+
+## Introduction
+
+Monitor and detect exposed secrets across your data sources, including code repositories, with Infisical Secret Scanning.
+
+For additional security, we recommend using our [CLI Secret Scanner](/cli/scanning-overview#automatically-scan-changes-before-you-commit) to check for exposed secrets before pushing your code changes.
+
+<Note>
+  Secret Scanning is a paid feature. If you're using Infisical Cloud, then it is
+  available under the **Enterprise Tier**. If you're self-hosting Infisical,
+  then you should contact team@infisical.com to purchase an enterprise license
+  to use it.
+</Note>
+
+## How Secret Scanning Works
+
+Secret Scanning consists of several components that enable you to quickly respond to secret leaks:
+
+- **Scanner Engine**: The core component that analyzes your code and detects potential secrets using pattern matching and entropy analysis
+- **Real-time Monitoring**: Provides continuous surveillance of your repositories for immediate detection of exposed secrets
+- **Alert System**: Notifies organization admins via email when secrets are detected
+- **Risk Management**: Allows tracking and managing detected secrets with different status options
+- **Data Sources**: Integrates with various data sources and version control systems
+- **Customizable Rules**: Supports ignore patterns and custom configurations to reduce false positives
+
+These components work together to provide comprehensive secret detection and incident response capabilities.
+
+### Data Sources
+
+Data sources are configured integrations with external platforms, such as a GitHub organization or a GitLab group, that establish secure connections for scanning purposes using [App Connections](/integrations/app-connections/overview).
+
+A data source acts as a secure intermediary between the external system and the scanner engine. It manages a collection of scannable resources (such as repositories) and handles the authentication and communication required for scanning operations.
+
+![data sources](/images/platform/secret-scanning/secret-scanning-data-sources.png)
+
+### Resources
+
+Resources are the atomic, scannable units, such as a repository, that can be monitored for secret exposure. Resources are added automatically when a data source is scanned and updated when scanning events are triggered, such as when a user pushes changes to GitHub.
+
+Each resource maintains its own scanning history and status, allowing for granular monitoring and management of secret scanning across your organization.
+
+![resources](/images/platform/secret-scanning/secret-scanning-resources.png)
+
+### Scans
+
+Scans can be initiated in two ways:
+
+1. **Full Scan** - Manually triggered scan that comprehensively checks either all resources associated with a data source or a single selected resource.
+
+2. **Diff Scan** - Automatically executed when **Auto-Scan** is enabled on a data source. This scan type specifically focuses on updates to existing resources.
+
+All scan activities can be monitored in real-time through the Infisical UI, which displays:
+
+- Current scan status
+- Timestamp of the scan
+- Resource(s) being scanned
+- Detection results (whether any secrets were found)
+
+![scans](/images/platform/secret-scanning/secret-scanning-scans.png)
+
+### Findings
+
+Findings are automatically generated when secret leaks are detected during scanning operations. Each finding contains comprehensive information including:
+
+- The specific scanning rule that identified the leak
+- File location and line number where the secret was found
+- Resource-specific details (e.g., commit hash and author for Git repositories)
+
+Findings are initially marked as **Unresolved** and can be updated to one of the following statuses with additional remarks:
+
+- **Resolved** - The issue has been addressed
+- **False Positive** - The detection was incorrect
+- **Ignore** - The finding can be safely disregarded
+
+These status options help teams effectively track and manage the lifecycle of detected secret leaks.
+
+![findings](/images/platform/secret-scanning/secret-scanning-findings.png)
+
+### Configuration
+
+You can configure custom scanning rules and exceptions by updating your project's scanning configuration via the UI or API.
+
+The configuration options allow you to:
+
+- Define custom scanning patterns and rules
+- Set up ignore patterns to reduce false positives
+- Specify file path exclusions
+- Configure entropy thresholds for secret detection
+- Add allowlists for known safe patterns
+
+For detailed configuration options, expand the example configuration below.
+
+<Accordion title="Example Configuration">
+    ```toml
+    # Title for the configuration file
+    title = "Some title"
+
+    # This configuration is the foundation that can be expanded. If there are any overlapping rules
+    # between this base and the expanded configuration, the rules in this base will take priority.
+    # Another aspect of extending configurations is the ability to link multiple files, up to a depth of 2.
+    # "Allowlist" arrays get appended and may have repeated elements.
+    # "useDefault" and "path" cannot be used simultaneously. Please choose one.
+    [extend]
+    # useDefault will extend the base configuration with the default config:
+    # https://raw.githubusercontent.com/Infisical/infisical/main/cli/config/infisical-scan.toml
+    useDefault = true
+    # or you can supply a path to a configuration. Path is relative to where infisical cli
+    # was invoked, not the location of the base config.
+    path = "common_config.toml"
+
+    # An array of tables that contain information that define instructions
+    # on how to detect secrets
+    [[rules]]
+
+    # Unique identifier for this rule
+    id = "some-identifier-for-rule"
+
+    # Short human readable description of the rule.
+    description = "awesome rule 1"
+
+    # Golang regular expression used to detect secrets. Note Golang's regex engine
+    # does not support lookaheads.
+    regex = '''one-go-style-regex-for-this-rule'''
+
+    # Golang regular expression used to match paths. This can be used as a standalone rule or it can be used
+    # in conjunction with a valid `regex` entry.
+    path = '''a-file-path-regex'''
+
+    # Array of strings used for metadata and reporting purposes.
+    tags = ["tag","another tag"]
+
+    # A regex match may have many groups, this allows you to specify the group that should be used as (which group the secret is contained in)
+    # its entropy checked if `entropy` is set.
+    secretGroup = 3
+
+    # Float representing the minimum shannon entropy a regex group must have to be considered a secret.
+    # Shannon entropy measures how random a data is. Since secrets are usually composed of many random characters, they typically have high entropy
+    entropy = 3.5
+
+    # Keywords are used for pre-regex check filtering.
+    # If rule has keywords but the text fragment being scanned doesn't have at least one of it's keywords, it will be skipped for processing further.
+    # Ideally these values should either be part of the identifier or unique strings specific to the rule's regex
+    # (introduced in v8.6.0)
+    keywords = [
+        "auth",
+        "password",
+        "token",
+    ]
+
+    # You can include an allowlist table for a single rule to reduce false positives or ignore commits
+    # with known/rotated secrets
+    [rules.allowlist]
+    description = "ignore commit A"
+    commits = [ "commit-A", "commit-B"]
+    paths = [
+        '''go\.mod''',
+        '''go\.sum'''
+    ]
+    # note: (rule) regexTarget defaults to check the _Secret_ in the finding.
+    # if regexTarget is not specified then _Secret_ will be used.
+    # Acceptable values for regexTarget are "match" and "line"
+    regexTarget = "match"
+    regexes = [
+        '''process''',
+        '''getenv''',
+    ]
+    # note: stopwords targets the extracted secret, not the entire regex match
+    # if the extracted secret is found in the stopwords list, the finding will be skipped (i.e not included in report)
+    stopwords = [
+        '''client''',
+        '''endpoint''',
+    ]
+
+
+    # This is a global allowlist which has a higher order of precedence than rule-specific allowlists.
+    # If a commit listed in the `commits` field below is encountered then that commit will be skipped and no
+    # secrets will be detected for said commit. The same logic applies for regexes and paths.
+    [allowlist]
+    description = "global allow list"
+    commits = [ "commit-A", "commit-B", "commit-C"]
+    paths = [
+        '''gitleaks\.toml''',
+        '''(.*?)(jpg|gif|doc)'''
+    ]
+
+    # note: (global) regexTarget defaults to check the _Secret_ in the finding.
+    # if regexTarget is not specified then _Secret_ will be used.
+    # Acceptable values for regexTarget are "match" and "line"
+    regexTarget = "match"
+
+    regexes = [
+        '''219-09-9999''',
+        '''078-05-1120''',
+        '''(9[0-9]{2}|666)-\d{2}-\d{4}''',
+    ]
+    # note: stopwords targets the extracted secret, not the entire regex match
+    # if the extracted secret is found in the stopwords list, the finding will be skipped (i.e not included in report)
+    stopwords = [
+        '''client''',
+        '''endpoint''',
+    ]
+    ```
+
+</Accordion>
+
+![config](/images/platform/secret-scanning/secret-scanning-config.png)
+
+## Ignoring Known Secrets
+
+If you're intentionally committing a test secret that the secret scanner might flag, you can instruct Infisical to overlook that secret with the methods listed below.
+
+### infisical-scan:ignore
+
+To ignore a secret contained in line of code, simply add `infisical-scan:ignore ` at the end of the line as comment in the given programming.
+
+```js example.js
+function helloWorld() {
+  console.log("8dyfuiRyq=vVc3RRr_edRk-fK__JItpZ"); // infisical-scan:ignore
+}
+```
+
+### .infisicalignore
+
+An alternative method to exclude specific findings involves creating a .infisicalignore file at your repository's root.
+You can then add the fingerprints of the findings you wish to exclude. The [Infisical scan](/cli/scanning-overview) report provides a unique Fingerprint for each secret found.
+By incorporating these Fingerprints into the .infisicalignore file, Infisical will skip the corresponding secret findings in subsequent scans.
+
+```.ignore .infisicalignore
+bea0ff6e05a4de73a5db625d4ae181a015b50855:frontend/components/utilities/attemptLogin.js:stripe-access-token:147
+bea0ff6e05a4de73a5db625d4ae181a015b50855:backend/src/json/integrations.json:generic-api-key:5
+1961b92340e5d2613acae528b886c842427ce5d0:frontend/components/utilities/attemptLogin.js:stripe-access-token:148
+```

docs/documentation/platform/secrets-mgmt/concepts/access-control.mdx

@@ -0,0 +1,33 @@
+---
+title: "Scoping Secrets"
+description: "Learn how access to secrets is controlled in Infisical."
+---
+
+## Secret Hierarchy
+
+Every secret in Infisical is scoped to an environment and a path.
+
+- An environment separates where secrets are used, such as `development`, `staging`, or `production`.
+- A path is an (optional) namespace within an environment that groups related secrets such as `/postgres`, `/redis`, or per-service paths like `/service-a`.
+
+This structure makes it easy to organize secrets by team, service, or environment, and sets the foundation for controlling who can access what.
+
+## Access Control
+
+Access control determines who (or what) can access a secret and under what conditions. Without clear policies, even securely stored secrets can be misused or exposed.
+
+To control access to secrets, you configure role-based permissions at the project level. These permissions determine which environments and paths a user or machine identity with that role can access. For example, an engineer might have a role that allows them to read secrets in the `development` environment but not those in the `production` environment.
+
+This model follows the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege) such that each user or machine identity has access only to the secrets it needs — and nothing more.
+
+## Advanced Capabilities
+
+Beyond basic role assignments, Infisical includes additional access control mechanisms for more advanced use cases:
+
+- Access approvals: Users can request access to specific environments or paths. Access can be temporary and reviewed before it is granted, reducing long-term exposure.
+
+- Secret change approvals: Updates to sensitive secrets can require approval before taking effect. This adds control in environments where unreviewed changes pose risk.
+
+- Attribute-based access control (ABAC): Permissions can be matched against metadata on a user or machine identity — such as team, service, or environment — enabling dynamic access rules without manual role changes.
+
+All access and approval actions are logged, so it’s always possible to trace who accessed what, when, and under what conditions.

docs/documentation/platform/secrets-mgmt/concepts/dynamic-secrets.mdx

@@ -0,0 +1,22 @@
+---
+title: "Dynamic Secrets"
+description: "Learn what dynamic secrets are, why they're useful, and how Infisical enables them."
+---
+
+## What is a Dynamic Secret?
+
+A _dynamic secret_ is a time-bound credential generated on demand for a specific user or system. Unlike _static secrets_, which are created and stored ahead of time, or rotated credentials, which are periodically replaced, dynamic secrets don’t exist until they’re requested — and automatically expire shortly after use.
+
+Each secret is unique to the identity that requested it, reducing the risk of reuse, long-term exposure, or accidental leaks. Because they are short-lived and tightly scoped, dynamic secrets are well suited for high-security environments, automated systems, and ephemeral workloads where access needs to be both temporary and auditable.
+
+By limiting the lifespan and visibility of credentials, dynamic secrets offer a strong alternative to managing long-lived secrets manually.
+
+## Dynamic Secrets in Infisical
+
+Infisical generates dynamic secrets in real time when a user or machine identity requests access. Each secret is uniquely scoped to the requesting identity, valid just-in-time only for a limited duration, and automatically revoked after it expires.
+
+Because they are short-lived and identity-specific, dynamic secrets reduce the risk of credential reuse, accidental exposure, or long-term persistence across environments.
+
+When supported for a given integration, using dynamic secrets is strongly recommended. Infisical currently supports dynamic secret templates for commonly used systems including [PostgreSQL](/documentation/platform/dynamic-secrets/postgresql), [MySQL](/documentation/platform/dynamic-secrets/mysql), [Microsoft SQL Server](/documentation/platform/dynamic-secrets/mssql), [MongoDB Atlas](/documentation/platform/dynamic-secrets/mongo-db), [Redis](/documentation/platform/dynamic-secrets/redis), [AWS IAM](/documentation/platform/dynamic-secrets/aws-iam), [GCP IAM](/documentation/platform/dynamic-secrets/gcp-iam), [Azure Entra ID](/documentation/platform/dynamic-secrets/azure-entra-id), and more.
+
+To learn more, refer to the [dynamic secrets documentation](/documentation/platform/dynamic-secrets/overview).

docs/documentation/platform/secrets-mgmt/concepts/secrets-delivery.mdx

@@ -0,0 +1,96 @@
+---
+title: "Delivering Secrets"
+description: "Learn how to get secrets out of Infisical and into the systems, applications, and environments that need them."
+---
+
+Once secrets are stored and scoped in Infisical, the next step is delivering them securely to the systems and applications that need them.
+
+Infisical supports many delivery methods to match a wide range of environments — from [local development](/documentation/platform/secrets-mgmt/concepts/secrets-delivery#local-development%2C-scripts%2C-and-one-off-tasks) to [Kubernetes workloads](/documentation/platform/secrets-mgmt/concepts/secrets-delivery#kubernetes-workloads), [CI/CD pipelines](/documentation/platform/secrets-mgmt/concepts/secrets-delivery#ci%2Fcd-pipelines), [infrastructure-as-code tools](/documentation/platform/secrets-mgmt/concepts/secrets-delivery#infrastructure-as-code-and-automation-tools), and more.
+
+The table below provides a quick overview of which delivery method may be suitable to use based on your environment and how secrets are consumed:
+
+| Use Case / Environment                                | Recommended Method(s)                                                                                                                         | Consumes Secrets As          | Notes                                                              |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------ |
+| Local development or scripting                        | [Infisical CLI](/cli/overview)                                                                                                                | Environment variables        | Easiest way to inject secrets during local dev or debugging        |
+| Application code fetching at runtime                  | [SDKs](/sdks/overview), [HTTP API](/api-reference/overview/introduction)                                                                      | In-memory / API call         | Full control in app code; supports dynamic or ephemeral fetching   |
+| VMs, containers, or CI jobs needing preloaded secrets | [Infisical Agent](/integrations/platforms/infisical-agent)                                                                                    | Env vars or files            | Good for non-interactive workloads; avoids inline secret fetch     |
+| GitHub Actions                                        | [Secrets Action](https://github.com/Infisical/secrets-action), [Secret Syncs](/integrations/secret-syncs/github)                              | Env vars or files            | Use Action for dynamic fetch; use Syncs to preload into GitHub     |
+| GitLab CI, Jenkins, other CI                          | [Infisical CLI](/cli/overview), [Infisical Agent](/integrations/platforms/infisical-agent), [Secret Syncs](/integrations/secret-syncs/gitlab) | Env vars or files            | Choose based on timing — fetch at runtime vs. pre-populate ahead   |
+| Kubernetes (declarative secrets)                      | [Kubernetes Operator](/integrations/platforms/kubernetes/overview)                                                                            | Kubernetes Secrets           | Syncs from Infisical into native Kubernetes Secrets                |
+| Kubernetes (ESO-based workflows)                      | [External Secrets Operator (ESO)](https://external-secrets.io/latest/provider/infisical/)                                                     | Kubernetes Secrets           | Reuses existing ESO setup; Infisical acts as a provider            |
+| Kubernetes (file-based, no K8s secrets)               | [Kubernetes Agent Injector](/integrations/platforms/kubernetes-injector)                                                                      | Mounted files                | Injects secrets via init container into volume at pod startup      |
+| Kubernetes (file-based, with rotation)                | [Kubernetes CSI Provider](/integrations/platforms/kubernetes-csi)                                                                             | Mounted files                | Uses CSI driver to mount secrets as files with automatic rotation  |
+| Image builds (VMs or containers)                      | [Packer Plugin](/integrations/frameworks/packer)                                                                                              | Env vars or files            | Inject secrets at image build time                                 |
+| Ansible automation                                    | [Ansible Collection](/integrations/platforms/ansible)                                                                                         | Variables                    | Runtime secret fetching in playbooks using lookup plugin           |
+| Terraform / Pulumi                                    | [Terraform Provider](/integrations/frameworks/terraform), [Pulumi](/integrations/frameworks/pulumi)                                           | Inputs / ephemeral resources | Use ephemeral for security; avoids storing secrets in state        |
+| Third-party platforms (GitHub, AWS, etc.)             | [Secret Syncs](/integrations/secret-syncs/overview)                                                                                           | Preloaded secrets            | Push secrets to platforms that can't fetch directly from Infisical |
+
+From here, you can explore the delivery method that best matches your environment:
+
+## Local Development, Scripts, and One-Off Tasks
+
+For local development, one-off scripts, or basic automation, the [Infisical CLI](/cli/overview) is a quick and flexible option.
+
+Instead of using a `.env` file, you can use [`infisical run`](/cli/commands/run) to inject secrets as environment variables directly into your development process. This provides a cleaner and more secure workflow. You can also use [`infisical secrets`](/cli/commands/secrets#infisical-secrets) to perform CRUD operations on secrets from the command line, which works well for debugging, local tooling, and lightweight scripting.
+
+To learn more, refer to the [CLI quickstart](cli/usage).
+
+## Applications and Services
+
+When secrets need to be accessed directly from within application code, Infisical provides SDKs for [Node.js](https://github.com/Infisical/node-sdk-v2), [Python](https://github.com/Infisical/python-sdk-official), [Go](/sdks/languages/go), [Java](https://github.com/Infisical/java-sdk), [.NET](https://github.com/Infisical/infisical-dotnet-sdk), [C++](https://github.com/Infisical/infisical-cpp-sdk), [Rust](https://github.com/Infisical/rust-sdk), and [Ruby](/sdks/languages/ruby).
+
+These SDKs let services fetch secrets at runtime or startup. For unsupported languages or if you prefer direct integration, you can use the fully documented [HTTP API](/api-reference/overview/introduction) to fetch secrets within your application logic.
+
+This approach gives you fine-grained control but also requires managing authentication and caching.
+
+## Virtual Machines(VMs), Containers, and CI Environments
+
+For systems that shouldn’t fetch secrets themselves — such as production VMs, Docker containers, or CI jobs — the [Infisical Agent](/integrations/platforms/infisical-agent) can be used to sync secrets into the local environment on their behalf.
+
+The agent runs as a lightweight background process and supports injecting secrets into files, environment variables, or application config formats. It's especially useful for non-interactive workloads that expect secrets to already exist at runtime.
+
+You can run the agent as a standalone binary, as a Docker sidecar, or embedded in automation scripts. It works well in environments like:
+
+- VMs that need secrets provisioned at startup.
+- [Docker Swarm](/integrations/platforms/docker-swarm-with-agent) services using shared volumes.
+- [ECS tasks](/integrations/platforms/ecs-with-agent) using EFS for shared secret delivery.
+
+## CI/CD Pipelines
+
+For CI/CD pipelines, the right method depends on the platform.
+
+- On GitHub Actions, the [Infisical Secrets Action](https://github.com/Infisical/secrets-action) provides a native integration that injects secrets as environment variables or `.env` files during workflows. It supports authentication via [AWS IAM](/documentation/platform/identities/aws-auth), [OIDC](/documentation/platform/identities/oidc-auth/github), or [Universal Auth](/documentation/platform/identities/universal-auth) using a Machine Identity.
+- On other CI platforms like GitLab CI, CircleCI, or Jenkins, the CLI or Agent may be used depending on how secrets are consumed — whether at runtime or during setup.
+
+Some CI/CD systems also support [Secret Syncs](/integrations/secret-syncs/overview) as an alternative. Instead of fetching secrets dynamically, you can configure Infisical to forward secrets into [GitHub Actions](/integrations/secret-syncs/github), [GitLab CI](/integrations/secret-syncs/gitlab), and similar platforms ahead of time — allowing them to be used as native environment secrets during jobs.
+
+## Kubernetes Workloads
+
+Infisical supports multiple options for delivering secrets into Kubernetes, each designed to match different operational models and consumption patterns:
+
+- [Infisical Kubernetes Operator](/integrations/platforms/kubernetes/overview): A set of CRDs that sync secrets from Infisical into Kubernetes Secrets, push secrets from Kubernetes back to Infisical, and manage dynamic secrets with automatic leases. Best suited for teams using declarative workflows and wanting to treat secrets as part of infrastructure code.
+
+- [External Secrets Operator (ESO)](https://external-secrets.io/latest/provider/infisical/): Enables syncing Infisical secrets into Kubernetes by defining ExternalSecret resources. Ideal if your team already uses ESO as a centralized way to fetch secrets from multiple providers.
+
+- [Infisical Agent Injector](/integrations/platforms/kubernetes-injector): A Kubernetes mutating admission webhook that injects an init container into your pods. The injected container syncs secrets from Infisical into a shared volume at startup, making them available as files. Useful for workloads that expect file-based secrets and where avoiding Kubernetes Secrets entirely is preferred.
+
+- [Infisical CSI Provider](/integrations/platforms/kubernetes-csi): Integrates with the Kubernetes Secrets Store CSI Driver to mount secrets as files in pods. Supports automatic rotation and fine-grained control over how secrets are structured and updated. Suitable for environments that require file-based secret delivery with rotation, without persisting Kubernetes Secrets.
+
+These methods provide secure, declarative integrations with Kubernetes-native workflows.
+
+## Forwarding to Third-Party Platforms
+
+In some cases, secrets must be delivered into systems that can’t fetch them from Infisical directly.
+
+[Secret Syncs](/integrations/secret-syncs/overview) allow you to forward secrets to platforms such as [GitHub](/integrations/secret-syncs/github), [GitLab](/integrations/secret-syncs/gitlab), [AWS Secrets Manager](/integrations/secret-syncs/aws-secrets-manager), [Vercel](/integrations/secret-syncs/vercel), and more.
+
+This is useful when external systems require secrets to be available ahead of time or expect them in a specific location.
+
+## Infrastructure-as-Code and Automation Tools
+
+Infisical integrates with common IaC and automation tools to help you securely inject secrets into your infrastructure provisioning workflows:
+
+- [Terraform](/integrations/frameworks/terraform): Use the official Infisical Terraform provider to fetch secrets either as ephemeral resources (never written to state files) or as traditional data sources. Ideal for managing cloud infrastructure while keeping secrets secure and version-safe.
+- [Pulumi](/integrations/frameworks/pulumi): Integrate Infisical into Pulumi projects using the Terraform Bridge, allowing you to fetch and manage secrets in TypeScript, Go, Python, or C# — without changing your existing workflows.
+- [Ansible](/integrations/platforms/ansible): Retrieve secrets from Infisical at runtime using the official Ansible Collection and lookup plugin. Works well for dynamic configuration during playbook execution.
+- [Packer](/integrations/frameworks/packer): Inject secrets into VM or container images at build time using the Infisical Packer Plugin — useful for provisioning base images that require secure configuration values.

docs/documentation/platform/secrets-mgmt/concepts/secrets-mgmt.mdx

@@ -0,0 +1,18 @@
+---
+title: "Secrets Management"
+description: "Learn what is secrets management and why it matters for building secure systems."
+---
+
+## What is Secret?
+
+A _secret_ is a confidential value used by an application such as database credential, API key, or other configuration.
+
+In most cases, secrets allow applications to access systems and control how they behave across the development cycle — for example, an application might use a database password stored in an environment variable like `DB_PASSWORD` to connect to production data. These secrets must be kept secure to protect infrastructure and data.
+
+## What is Secrets Management?
+
+As infrastructure scales and systems become more distributed, [secrets sprawl](https://infisical.com/blog/what-is-secret-sprawl). Without consistent security practices, secrets get hardcoded in source code, exposed in environment variables, left unrotated for long periods, and scattered across systems without clear visibility into who can access them.
+
+To solve secret sprawl, organizations rely on [secrets management](https://infisical.com/blog/what-is-secrets-management): the practice of centralizing secrets and managing them through well-defined workflows. This includes secure storage, fine-grained access controls, automatic rotation, audit logging, and support for dynamic, short-lived credentials.
+
+A consistent approach makes it easier to keep secrets safe, reduce risk, and operate reliably across environments.

docs/documentation/platform/secrets-mgmt/concepts/secrets-rotation.mdx

@@ -0,0 +1,18 @@
+---
+title: "Secrets Rotation"
+description: "Learn what secrets rotation is, why it matters, and how Infisical enables it."
+---
+
+## What is Secrets Rotation?
+
+Secrets rotation is the process of regularly replacing credentials like API keys, database passwords, and tokens to reduce the risk of long-term exposure. Even if a secret is compromised, frequent rotation limits how long it can be used.
+
+Without rotation, secrets often go unchanged for months or years — hardcoded in codebases, embedded in CI pipelines, or shared across environments. Over time, this increases the risk of leaks, misuse, and operational blind spots.
+
+## Secrets Rotation in Infisical
+
+Infisical automates rotation using a rolling lifecycle model where new credentials are issued on a fixed schedule with previous ones remaining temporarily valid to give systems time to update without disruption. Each secret moves through three phases: active, inactive, and eventually revoked. This ensures that applications continue to function smoothly throughout the rotation process.
+
+When rotation is applicable for a given secret type, using it is strongly recommended. Infisical supports configuring automatic rotation for a growing set of use cases including [PostgreSQL](/documentation/platform/secret-rotation/postgres-credentials), [MySQL](/documentation/platform/secret-rotation/mysql-credentials), [Microsoft SQL Server](/documentation/platform/secret-rotation/mssql-credentials), [OracleDB](/documentation/platform/secret-rotation/oracledb-credentials), [LDAP](/documentation/platform/secret-rotation/ldap-password), [AWS IAM users](/documentation/platform/secret-rotation/aws-iam-user-secret), [Azure](/documentation/platform/secret-rotation/azure-client-secret) and [Okta](/documentation/platform/secret-rotation/okta-client-secret) client secrets, and more.
+
+To learn more, refer to the [secrets rotation documentation](/documentation/platform/secret-rotation/overview).

docs/documentation/platform/secrets-mgmt/overview.mdx

@@ -12,6 +12,6 @@ Core capabilities include:
 
 - Secret Stores: Secure, versioned storage scoped by [project](/documentation/platform/secrets-mgmt/project), [environment](/documentation/platform/secrets-mgmt/project#project-environments), and [path](/documentation/platform/folder).
 - [Access Control](/documentation/platform/access-controls/overview): Fine-grained, identity-aware permissions for users and machines
-- Secret Delivery: Access secrets via [CLI](/cli/overview), [SDKs](/sdks/overview) (Go, Node.js, Python, etc.), [HTTP API](/api-reference/overview/introduction), [agents](/integrations/platforms/infisical-agent), [Kubernetes Operator](/integrations/platforms/kubernetes/overview), [External Secrets Operator (ESO)](https://external-secrets.io/latest/provider/infisical), and more.
-- Lifecycle Automation: Automate [secret rotation](/documentation/platform/secret-rotation/overview), generate [dynamic secrets](/documentation/platform/dynamic-secrets/overview), and enforce [approval-based workflows](/documentation/platform/pr-workflows).
+- [Secret Delivery](/documentation/platform/secrets-mgmt/concepts/secrets-delivery): Access secrets via [CLI](/cli/overview), [SDKs](/sdks/overview) (Go, Node.js, Python, etc.), [HTTP API](/api-reference/overview/introduction), [agents](/integrations/platforms/infisical-agent), [Kubernetes Operator](/integrations/platforms/kubernetes/overview), [External Secrets Operator (ESO)](https://external-secrets.io/latest/provider/infisical), and more.
+- Lifecycle Automation: Automate [secret rotation](/documentation/platform/secrets-mgmt/concepts/secrets-rotation), generate [dynamic secrets](/documentation/platform/secrets-mgmt/concepts/dynamic-secrets), and enforce [approval-based workflows](/documentation/platform/pr-workflows).
 - [Secrets Syncs](/integrations/secret-syncs/overview): Push secrets to external services like [GitHub](/integrations/secret-syncs/github), [GitLab](/integrations/secret-syncs/gitlab), [AWS Secrets Manager](/integrations/secret-syncs/aws-secrets-manager), [Vercel](/integrations/secret-syncs/vercel), and more.

docs/documentation/platform/ssh/concepts/ssh-certificates.mdx

@@ -0,0 +1,26 @@
+---
+title: "SSH Certificates"
+description: "Learn what SSH certificates are, why they're useful, and how they enable secure, scalable infrastructure access."
+---
+
+SSH access is ubiquitous — It's how engineers, scripts, and platforms across the world remotely administer Linux systems. That said, as teams and systems grow, managing access with static SSH keys becomes brittle and issues like key sprawl, unclear boundaries, and poor revocation hygiene start to emerge.
+
+_SSH certificates_ offer an alternative approach to securing and managing access at scale.
+
+## What is an SSH Certificate?
+
+An _SSH certificate_ is a short-lived, signed credential that proves a user or host’s identity. Unlike static SSH keys, which are distributed and managed manually, SSH certificates rely on a centralized certificate authority (CA) to vouch for identities.
+There are two types of SSH certificates:
+
+- User certificates: Issued to users to authenticate with remote hosts
+- Host certificates: Issued to hosts so clients can verify they're trusted
+
+Because certificates are time-bound and centrally managed, they’re easier to audit, revoke, and scale across infrastructure.
+
+## SSH with Infisical
+
+Infisical SSH gives you a secure, scalable way to manage infrastructure access using SSH certificates — without the overhead of running your own certificate authority, wiring trust across hosts, or building issuance workflows from scratch.
+
+It replaces long-lived SSH keys with short-lived, identity-bound certificates and handles all the moving parts for you: operating CAs, configuring trust between users and hosts, and issuing certificates on demand. With Infisical SSH, you can register a host with [`infisical ssh add-host`](/docs/cli/commands/ssh#infisical-ssh-add-host), then connect with [`infisical ssh connect`](/docs/cli/commands/ssh#infisical-ssh-connect) — that’s all it takes.
+
+The result is centralized, auditable SSH access that’s easy to use and built to scale with your infrastructure.

docs/documentation/platform/ssh/overview.mdx

@@ -1,201 +1,15 @@
 ---
-title: "Overview"
+title: "Infisical SSH"
 sidebarTitle: "Overview"
-description: "Learn how to securely provision user SSH access to your infrastructure using SSH certificates."
+description: "Learn how to manage secure, short-lived SSH access to infrastructure using certificates."
 ---
 
-## Concept
+Infisical SSH provides a secure, certificate-based solution for managing SSH access to infrastructure.
+It replaces long-lived SSH keys with short-lived, identity-bound certificates to reduce key sprawl, simplify access control, and improve auditability.
 
-Infisical SSH can be configured to provide users on your team short-lived, secure SSH access to infrastructure. Under the hood, it uses SSH certificates
-and improves upon traditional SSH key-based authentication by mitigating private key compromise, static key management,
-unauthorized access, and SSH key sprawl.
+Core capabilities include:
 
-The following entities are important to understand when configuring and using Infisical SSH:
-
-- Administrator: An individual on your team who is responsible for configuring Infisical SSH.
-- Users: Other individuals that gain access to remote hosts through Infisical SSH.
-- Host: A remote machine (e.g. EC2 instance, GCP VM, Azure VM, on-prem Linux server, Raspberry Pi, VMware VM, etc.) that users need SSH access to that is registered with Infisical SSH.
-
-## Workflow
-
-The typical workflow for using Infisical SSH consists of the following steps:
-
-1. The administrator registers a remote host with Infisical using the Infisical CLI via the `infisical ssh add-host` command.
-2. The administrator configures Infisical SSH to grant users access to the remote host.
-3. User(s) access the remote host using the Infisical CLI via the `infisical ssh connect` command.
-
-## Admin Guide for Configuring Infisical SSH
-
-In the following steps, we explore how to configure Infisical SSH to control and streamline your team's SSH access to infrastructure. As part of this guide,
-we will register a remote host with Infisical through a [machine identity](/documentation/platform/identities/machine-identities) and configure Infisical to grant user(s) access to the remote host.
-
-<Steps>
-  <Step title="Create an Infisical SSH project">
-    Start by creating a new Infisical SSH project in Infisical.
-    
-    ![ssh project create](/images/platform/ssh/v2/ssh-create-project.png)
-  </Step>
-  <Step title="Create a machine identity for bootstrapping Infisical SSH">
-    2.1. Follow the instructions [here](/documentation/platform/identities/universal-auth) to configure a [machine identity](/documentation/platform/identities/machine-identities) in Infisical with Universal Auth.
-
-    By the end of this step, you should have a **Client ID** and **Client Secret** on hand as part of the Universal Auth configuration for the identity to authenticate with Infisical
-    as part of registering a remote host in step 3.
-
-    <Note>
-        You may use other authentication methods as suitable (e.g. [AWS Auth](/documentation/platform/identities/aws-auth), [Azure Auth](/documentation/platform/identities/azure-auth), [GCP Auth](/documentation/platform/identities/gcp-auth), etc.) as part of the machine identity configuration but, to keep this example simple, we will be using Universal Auth.
-    </Note>
-
-    2.2. Add the machine identity to the Infisical SSH project you created in the previous step and assign it the **SSH Host Bootstrapper** role.
-
-      This role grants the ability to **Create** and **Issue Host Certificates** on the **SSH Host** resource; this will enable the linked machine identity to bootstrap a remote host with Infisical
-      and establish the necessary configuration on it.
-
-      <Tip>
-          If you plan to use a custom role to bootstrap SSH hosts, ensure the role has the **Create** and **Issue Host Certificates** on the **SSH Host** resource.
-      </Tip>
-
-    ![ssh add identity to project](/images/platform/ssh/v2/ssh-add-identity-to-project.png)
-
-  </Step>
-  <Step title="Configure the remote host">
-    3.1. Follow the instructions [here](/cli/overview) to install the Infisical CLI onto the remote host.
-    
-    3.2. Run the commands below to register the remote host with Infisical.
-
-    Use the **Client ID** and **Client Secret** from the machine identity you created in step 2.1 as part of the `infisical login` command
-    to obtain an access token and save it as an environment variable.
-
-    ```bash
-    export INFISICAL_TOKEN=$(infisical login --method=universal-auth --client-id=<identity-client-id> --client-secret=<identity-client-secret> --silent --plain)
-    ```
-
-    Next, use the `infisical ssh add-host` command to register the remote host with Infisical. As part of this command, input the ID of the Infisical SSH project you created in step 1 for the `--projectId` flag and the hostname of the remote host for the `--hostname` flag.
-
-    ```bash
-    sudo infisical ssh add-host --projectId=<project-id> --hostname=<hostname> --token="$INFISICAL_TOKEN" --write-user-ca-to-file --write-host-cert-to-file --configure-sshd
-    ```
-
-    <Tip>
-        Note that if you're self-hosting Infisical, you can use the `--domain` flag on the `infisical login` command to specify the domain of your Infisical instance.
-
-        For more information on the `infisical ssh add-host` command, please refer to the Infisical CLI [documentation](/cli/overview).
-    </Tip>
-
-    If successful, you should see output similar to the following:
-
-    ```bash
-    ✅ Successfully registered host: <hostname>
-    📁 Wrote User CA public key to: /etc/ssh/infisical_user_ca.pub
-    📁 Wrote host certificate to: /etc/ssh/ssh_host_ed25519_key-cert.pub
-    📄 Updated sshd_config entries
-    ```
-
-    Finally, use the following command to reload the SSH daemon on the remote host to apply the changes:
-
-    ```bash
-    sudo systemctl reload sshd
-    ```
-
-    <Note>
-      The command may differ depending on the host. For older versions of Ubuntu/Debian/CentOS, you may need to use `sudo service ssh reload` instead;
-      for Alpine or minimal systems, `/etc/init.d/sshd reload`.
-    </Note>
-
-    Back in Infisical, you should now see the remote host you just registered in the Infisical SSH project you created in step 1 under the **Hosts** tab.
-
-    ![ssh hosts](/images/platform/ssh/v2/ssh-added-hosts.png)
-
-  </Step>
-  <Step title="Grant users access to the remote host">
-    4.1. Add the user(s) you wish to grant access to the remote host to the Infisical SSH project under Access Control > Users.
-    
-    ![ssh hosts](/images/platform/ssh/v2/ssh-add-user.png)
-    
-    4.2. On the registered host in the **Hosts** tab, click **Edit SSH Host** and add a login mapping for the user(s) you added in step 4.1.
-
-    The login mapping dictates what user(s) will be allowed access to the remote host and under a specific login user; in the allowed principals,
-    you should select user(s) part of the Infisical SSH project that will be allowed to login to the remote host as the login user.
-
-    For instance, if you add a mapping with the login user `ec2-user` to some users John and Alice in Infisical, then they will be allowed to login to the remote host as `ec2-user` which is a system user that
-    exists on the remote host.
-
-    ![ssh host mappings](/images/platform/ssh/v2/ssh-host-login-mappings.png)
-
-    <Note>
-        Note that you should configure authorized principals files for each login user you add to the remote host.
-    </Note>
-
-  </Step>
-</Steps>
-
-## User Guide for SSHing to a Host
-
-Once Infisical SSH is configured by an administrator, users can SSH to the remote host using the Infisical CLI.
-
-<Steps>
-    <Step title="Install the Infisical CLI">
-        Follow the instructions [here](/cli/overview) to install the Infisical CLI onto your local machine.
-    </Step>
-    <Step title="Connect to the remote host">
-        The `infisical ssh connect` command can be used in either interactive or non-interactive mode to connect to a remote host.
-
-        <Tabs>
-            <Tab title="Interactive Mode">
-                In interactive mode, you'll first need to authenticate with Infisical by running:
-
-                ```bash
-                infisical login
-                ```
-
-                Then simply run:
-
-                ```bash
-                infisical ssh connect
-                ```
-
-                You'll be prompted to select an SSH Host from a list of accessible hosts; this is based on project membership and login mappings configured on hosts by
-                the administrator.
-
-                ```bash
-                Use the arrow keys to navigate: ↓ ↑ → ←
-                ? Select an SSH Host:
-                ▸ ec2-12-345-678-910.ap-northeast-1.compute.amazonaws.com
-                ```
-
-                After selecting a host, you'll be prompted to select a login user from a list of allowed login users:
-
-                ```bash
-                ? Select Login User:
-                ▸ ec2-user
-                ```
-
-                If successful, you should be able to SSH to the remote host.
-
-                ```bash
-                ✔ ec2-54-199-104-116.ap-northeast-1.compute.amazonaws.com
-                ✔ ec2-user
-                ✔ SSH credentials successfully added to agent
-                Connecting to ec2-user@ec2-12-345-678-910.ap-northeast-1.compute.amazonaws.com...
-                ```
-            </Tab>
-            <Tab title="Non-Interactive Mode">
-                For CI/CD pipelines or automation scenarios, you can use the non-interactive mode with an Infisical token:
-
-                ```bash
-                infisical ssh connect \
-                  --hostname ec2-12-345-678-910.ap-northeast-1.compute.amazonaws.com \
-                  --login-user ec2-user \
-                  --out-file-path ~/.ssh/id_rsa-cert.pub \
-                  --token <your-infisical-token>
-                ```
-
-                This will:
-                - Connect to the specified hostname
-                - Use the specified login user
-                - Write the SSH credentials to the specified path instead of adding them to the SSH agent
-                - Authenticate using the provided Infisical token
-            </Tab>
-        </Tabs>
-    </Step>
-
-</Steps>
+- Certificate Authority (CA): Managed CA infrastructure for issuing short-lived SSH certificates.
+- Centralized Access Management: View all registered hosts, see who has access to each, and control permissions from a single interface.
+- Easy Host Registration & Connection: Quickly register hosts and connect using short-lived certificates without manual key distribution.
+- Audit Logging: Detailed records of certificate issuance and SSH access activity.

docs/documentation/platform/ssh/usage.mdx

@@ -0,0 +1,201 @@
+---
+title: "Overview"
+sidebarTitle: "Overview"
+description: "Learn how to securely provision user SSH access to your infrastructure using SSH certificates."
+---
+
+## Concept
+
+Infisical SSH can be configured to provide users on your team short-lived, secure SSH access to infrastructure. Under the hood, it uses SSH certificates
+and improves upon traditional SSH key-based authentication by mitigating private key compromise, static key management,
+unauthorized access, and SSH key sprawl.
+
+The following entities are important to understand when configuring and using Infisical SSH:
+
+- Administrator: An individual on your team who is responsible for configuring Infisical SSH.
+- Users: Other individuals that gain access to remote hosts through Infisical SSH.
+- Host: A remote machine (e.g. EC2 instance, GCP VM, Azure VM, on-prem Linux server, Raspberry Pi, VMware VM, etc.) that users need SSH access to that is registered with Infisical SSH.
+
+## Workflow
+
+The typical workflow for using Infisical SSH consists of the following steps:
+
+1. The administrator registers a remote host with Infisical using the Infisical CLI via the `infisical ssh add-host` command.
+2. The administrator configures Infisical SSH to grant users access to the remote host.
+3. User(s) access the remote host using the Infisical CLI via the `infisical ssh connect` command.
+
+## Admin Guide for Configuring Infisical SSH
+
+In the following steps, we explore how to configure Infisical SSH to control and streamline your team's SSH access to infrastructure. As part of this guide,
+we will register a remote host with Infisical through a [machine identity](/documentation/platform/identities/machine-identities) and configure Infisical to grant user(s) access to the remote host.
+
+<Steps>
+  <Step title="Create an Infisical SSH project">
+    Start by creating a new Infisical SSH project in Infisical.
+    
+    ![ssh project create](/images/platform/ssh/v2/ssh-create-project.png)
+  </Step>
+  <Step title="Create a machine identity for bootstrapping Infisical SSH">
+    2.1. Follow the instructions [here](/documentation/platform/identities/universal-auth) to configure a [machine identity](/documentation/platform/identities/machine-identities) in Infisical with Universal Auth.
+
+    By the end of this step, you should have a **Client ID** and **Client Secret** on hand as part of the Universal Auth configuration for the identity to authenticate with Infisical
+    as part of registering a remote host in step 3.
+
+    <Note>
+        You may use other authentication methods as suitable (e.g. [AWS Auth](/documentation/platform/identities/aws-auth), [Azure Auth](/documentation/platform/identities/azure-auth), [GCP Auth](/documentation/platform/identities/gcp-auth), etc.) as part of the machine identity configuration but, to keep this example simple, we will be using Universal Auth.
+    </Note>
+
+    2.2. Add the machine identity to the Infisical SSH project you created in the previous step and assign it the **SSH Host Bootstrapper** role.
+
+      This role grants the ability to **Create** and **Issue Host Certificates** on the **SSH Host** resource; this will enable the linked machine identity to bootstrap a remote host with Infisical
+      and establish the necessary configuration on it.
+
+      <Tip>
+          If you plan to use a custom role to bootstrap SSH hosts, ensure the role has the **Create** and **Issue Host Certificates** on the **SSH Host** resource.
+      </Tip>
+
+    ![ssh add identity to project](/images/platform/ssh/v2/ssh-add-identity-to-project.png)
+
+  </Step>
+  <Step title="Configure the remote host">
+    3.1. Follow the instructions [here](/cli/overview) to install the Infisical CLI onto the remote host.
+    
+    3.2. Run the commands below to register the remote host with Infisical.
+
+    Use the **Client ID** and **Client Secret** from the machine identity you created in step 2.1 as part of the `infisical login` command
+    to obtain an access token and save it as an environment variable.
+
+    ```bash
+    export INFISICAL_TOKEN=$(infisical login --method=universal-auth --client-id=<identity-client-id> --client-secret=<identity-client-secret> --silent --plain)
+    ```
+
+    Next, use the `infisical ssh add-host` command to register the remote host with Infisical. As part of this command, input the ID of the Infisical SSH project you created in step 1 for the `--projectId` flag and the hostname of the remote host for the `--hostname` flag.
+
+    ```bash
+    sudo infisical ssh add-host --projectId=<project-id> --hostname=<hostname> --token="$INFISICAL_TOKEN" --write-user-ca-to-file --write-host-cert-to-file --configure-sshd
+    ```
+
+    <Tip>
+        Note that if you're self-hosting Infisical, you can use the `--domain` flag on the `infisical login` command to specify the domain of your Infisical instance.
+
+        For more information on the `infisical ssh add-host` command, please refer to the Infisical CLI [documentation](/cli/overview).
+    </Tip>
+
+    If successful, you should see output similar to the following:
+
+    ```bash
+    ✅ Successfully registered host: <hostname>
+    📁 Wrote User CA public key to: /etc/ssh/infisical_user_ca.pub
+    📁 Wrote host certificate to: /etc/ssh/ssh_host_ed25519_key-cert.pub
+    📄 Updated sshd_config entries
+    ```
+
+    Finally, use the following command to reload the SSH daemon on the remote host to apply the changes:
+
+    ```bash
+    sudo systemctl reload sshd
+    ```
+
+    <Note>
+      The command may differ depending on the host. For older versions of Ubuntu/Debian/CentOS, you may need to use `sudo service ssh reload` instead;
+      for Alpine or minimal systems, `/etc/init.d/sshd reload`.
+    </Note>
+
+    Back in Infisical, you should now see the remote host you just registered in the Infisical SSH project you created in step 1 under the **Hosts** tab.
+
+    ![ssh hosts](/images/platform/ssh/v2/ssh-added-hosts.png)
+
+  </Step>
+  <Step title="Grant users access to the remote host">
+    4.1. Add the user(s) you wish to grant access to the remote host to the Infisical SSH project under Access Control > Users.
+    
+    ![ssh hosts](/images/platform/ssh/v2/ssh-add-user.png)
+    
+    4.2. On the registered host in the **Hosts** tab, click **Edit SSH Host** and add a login mapping for the user(s) you added in step 4.1.
+
+    The login mapping dictates what user(s) will be allowed access to the remote host and under a specific login user; in the allowed principals,
+    you should select user(s) part of the Infisical SSH project that will be allowed to login to the remote host as the login user.
+
+    For instance, if you add a mapping with the login user `ec2-user` to some users John and Alice in Infisical, then they will be allowed to login to the remote host as `ec2-user` which is a system user that
+    exists on the remote host.
+
+    ![ssh host mappings](/images/platform/ssh/v2/ssh-host-login-mappings.png)
+
+    <Note>
+        Note that you should configure authorized principals files for each login user you add to the remote host.
+    </Note>
+
+  </Step>
+</Steps>
+
+## User Guide for SSHing to a Host
+
+Once Infisical SSH is configured by an administrator, users can SSH to the remote host using the Infisical CLI.
+
+<Steps>
+    <Step title="Install the Infisical CLI">
+        Follow the instructions [here](/cli/overview) to install the Infisical CLI onto your local machine.
+    </Step>
+    <Step title="Connect to the remote host">
+        The `infisical ssh connect` command can be used in either interactive or non-interactive mode to connect to a remote host.
+
+        <Tabs>
+            <Tab title="Interactive Mode">
+                In interactive mode, you'll first need to authenticate with Infisical by running:
+
+                ```bash
+                infisical login
+                ```
+
+                Then simply run:
+
+                ```bash
+                infisical ssh connect
+                ```
+
+                You'll be prompted to select an SSH Host from a list of accessible hosts; this is based on project membership and login mappings configured on hosts by
+                the administrator.
+
+                ```bash
+                Use the arrow keys to navigate: ↓ ↑ → ←
+                ? Select an SSH Host:
+                ▸ ec2-12-345-678-910.ap-northeast-1.compute.amazonaws.com
+                ```
+
+                After selecting a host, you'll be prompted to select a login user from a list of allowed login users:
+
+                ```bash
+                ? Select Login User:
+                ▸ ec2-user
+                ```
+
+                If successful, you should be able to SSH to the remote host.
+
+                ```bash
+                ✔ ec2-54-199-104-116.ap-northeast-1.compute.amazonaws.com
+                ✔ ec2-user
+                ✔ SSH credentials successfully added to agent
+                Connecting to ec2-user@ec2-12-345-678-910.ap-northeast-1.compute.amazonaws.com...
+                ```
+            </Tab>
+            <Tab title="Non-Interactive Mode">
+                For CI/CD pipelines or automation scenarios, you can use the non-interactive mode with an Infisical token:
+
+                ```bash
+                infisical ssh connect \
+                  --hostname ec2-12-345-678-910.ap-northeast-1.compute.amazonaws.com \
+                  --login-user ec2-user \
+                  --out-file-path ~/.ssh/id_rsa-cert.pub \
+                  --token <your-infisical-token>
+                ```
+
+                This will:
+                - Connect to the specified hostname
+                - Use the specified login user
+                - Write the SSH credentials to the specified path instead of adding them to the SSH agent
+                - Authenticate using the provided Infisical token
+            </Tab>
+        </Tabs>
+    </Step>
+
+</Steps>