feat: add docs for Kosli Capture Managed Service

administration/kosli_capture/getting_started.md

@@ -0,0 +1,43 @@
+---
+title: "Getting started with Kosli Capture"
+sidebarTitle: "Getting started"
+description: "Learn how to configure Kosli Capture for your organization"
+tag: "BETA"
+---
+
+<Warning>
+Kosli Capture is still in active development. Its capabilities and configuration format may change, and onboarding is done together with Kosli's Customer Success team.
+</Warning>
+
+Kosli Capture is a managed service that runs on Kosli's infrastructure and connects to your cloud platform to observe the resources deployed there. To get set up with Kosli Capture you need to grant permissions to Kosli's cloud account and enable Kosli Capture within your Kosli org.
+
+## Overview
+
+Getting started with Kosli Capture involves two stages:
+
+<Steps>
+  <Step title="Prepare your environment">
+    Create an IAM role in your AWS account specifically for Kosli Capture. Kosli provides a CloudFormation template to simplify this process. The template requires a shared secret, which Kosli provides to you.
+  </Step>
+  <Step title="Enable Kosli Capture">
+    Enable Kosli Capture for your Kosli org, and the regular snapshots appear in Kosli.
+  </Step>
+</Steps>
+
+## Prepare your environment
+
+In order for Kosli Capture to reach into your cloud, to discover your ECS clusters and Lambdas, you need to grant permission to Kosli to do so.  Within AWS this requires the creation of an IAM role that Kosli can assume; the role will exist within your AWS account.
+
+To simplify this process, Kosli has created a CloudFormation template that contains a role with the minimum set of permissions needed by Kosli Capture.  The role can be assumed by Kosli and is protected by an external Id; each organization within Kosli has its own external Id.  The CloudFormation template can be downloaded from the Settings page for your organization within the Kosli UI.
+
+The CloudFormation template can be deployed within an AWS account, or can be attached to an AWS Organizational Unit (OU) as a StackSet; this latter option ensures the correct IAM permissions are rolled out to all AWS accounts within the OU.
+
+When used, the CloudFormation template will send your AWS account id to Kosli, so that we are automatically notified that your account is ready to be included in Kosli Capture.  Similarly, if you delete the CloudFormation stack we will be notified and know that the account is no longer to be included.
+
+## Enable Kosli Capture
+
+When you have created the IAM role, using the CloudFormation template, you can activate Kosli Capture within the Kosli user-interface.  Kosli Capture runs on a five-minute schedule, and once you have enabled it, Kosli Capture will pick up your environment the next time it runs - you should see environments and snapshots appearing within a few minutes.
+
+## Excluding resources
+
+If there are resources you do not wish to include within a Kosli Capture Managed snapshot, for example an ECS cluster that you consider to be out of scope, you can add an AWS tag to it indicating that the item should be skipped.  Adding a tag with the name `kosli.capture` and the value `false` will ensure that Kosli Capture skips over that resource.

administration/kosli_capture/overview.md

@@ -0,0 +1,46 @@
+---
+title: "Kosli Capture Managed Service"
+sidebarTitle: "Kosli Capture"
+description: "Learn how the Kosli Capture Managed Service snapshots your cloud environments from Kosli's infrastructure, with no software to install."
+tag: "BETA"
+---
+
+<Warning>
+Kosli Capture is still in active development. Its capabilities and configuration format may change, and onboarding is done together with Kosli's Customer Success team.
+</Warning>
+
+Kosli Capture is a managed service that runs on Kosli's infrastructure and connects to your cloud platform to observe the resources deployed there. You grant Kosli Capture a set of permissions, and it uses them to run a `kosli snapshot` every few minutes against the infrastructure you have allowed it to scan.
+
+Kosli also supports reporting from your own cloud accounts by running the Kosli CLI on a schedule. Kosli Capture inverts this, with Kosli running the regular [snapshots](/getting_started/environments) so there is no software for you to install.
+
+To set it up for your organization, see [Getting started with Kosli Capture](/administration/kosli_capture/getting_started).
+
+## Overview
+
+Kosli Capture connects to your cloud accounts using permissions that you manage.  You configure Kosli Capture by activating it for different AWS services, and Kosli Capture uses the permissions to regularly reach into your estate and record snapshots, sending the data into your Kosli organization.  Kosli Capture uses details about your infrastructure, such as the name of an ECS cluster, to build environments within Kosli.
+
+## Security
+
+The security of your cloud infrastructure is the primary driver behind the internal architecture of
+Kosli Capture. You grant a read-only IAM role in your account, protected by an external ID that acts
+as a shared secret between Kosli and you. On Kosli's side, each Kosli Capture job runs under a role
+scoped to your organization alone, so a worker running for another customer cannot reach your cloud
+account. Kosli Capture holds no customer data; snapshots go straight to Kosli through the same ingest
+path as your existing pipelines. See [Kosli Capture Security](/administration/kosli_capture/security)
+for the isolation model and the full list of permissions.
+
+## Hands-off operation
+
+Kosli Capture has been designed to operate with no on-going support from you.  Once the initial security permissions have been created, Kosli Capture will continue to operate in a headless mode.  Monitoring, maintenance and rotation of API keys is all handled automatically.  As your cloud infrastructure changes over time, Kosli Capture will continue to find resources without you needing to do anything; your application teams do not need to take any action in order to onboard their products and services into Kosli.
+
+## Finding resources
+
+Kosli Capture finds all supported resources within your AWS accounts, and determines which Kosli environment should hold the snapshots. Kosli Capture will create physical environments for you.
+
+Kosli Capture can [filter out resources based on AWS tags](/administration/kosli_capture/getting_started#excluding-resources).
+
+As your cloud environment evolves, such as the addition of new ECS clusters or the retirement of existing Lambdas, Kosli Capture automatically detects the changes. Because Kosli Capture creates physical environments as needed, when your infrastructure changes, Kosli will keep up. No changes to the configuration created during the initial setup are required.
+
+## Multiple AWS accounts
+
+Kosli Capture can operate across multiple AWS regions and accounts, allowing you to snapshot development, QA, pre-production, and production workloads with the same process.

administration/kosli_capture/security.md

@@ -0,0 +1,121 @@
+---
+title: Kosli Capture - Security
+sidebarTitle: Security
+description: "Learn about the security of Kosli Capture"
+tag: "BETA"
+---
+
+<Warning>
+Kosli Capture is still in active development. Its capabilities and configuration format may change, and onboarding is done together with Kosli's Customer Success team.
+</Warning>
+
+## Kosli Capture permissions
+
+The Kosli Capture managed service uses the public AWS APIs to extract information about your cloud environments.  In order to do this, you need to provide Kosli with an IAM role that allows access to these APIs.  The role is created and owned by you.  Kosli publishes a CloudFormation template, for use in AWS, showing the permissions needed.  The template is publicly accessible and can be used directly within an `aws cloudformation create-stack` call.
+
+The CloudFormation template we share with you includes a "phone-home" feature that notifies Kosli when a CloudFormation stack has been built from it; this allows us to pick up the AWS AccountId for the account in which you have used the CloudFormation template without you needing to do anything.  This automation is especially useful when you deploy the template as a StackSet within an Organizational Unit.
+
+### Assume role
+
+The IAM role defined within the CloudFormation template includes an "assume role" policy granting permission from Kosli.  This appears as:
+
+```yaml
+  KosliCaptureAccessRole:
+    Type: AWS::IAM::Role
+    Properties:
+      RoleName: !Ref RoleName
+      Description: >-
+        Read-only access for Kosli Capture SDLC compliance evidence collection.
+        Managed by CloudFormation; do not edit in place.
+      MaxSessionDuration: 3600
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Sid: AllowKosliToAssumeWithExternalId
+            Effect: Allow
+            Principal:
+              AWS: !Ref TrustedPrincipalArn
+            Action: sts:AssumeRole
+            Condition:
+              StringEquals:
+                sts:ExternalId: !Ref ExternalId
+```
+
+### All permissions needed
+
+The IAM role defined within the Cloudformation template includes a number of IAM policy statements, granting read-only access to some AWS APIs.  The statements are:
+
+```yaml
+Statement:
+
+  # How Capture finds what to snapshot. Discovery lists the ECS
+  # clusters in the account and reads each cluster's tags from the
+  # same DescribeClusters call.
+  #
+  # Worth knowing for a security review: these are inventory calls
+  # and none of them returns application data. DescribeTaskDefinition
+  # is the widest - a task definition holds the container image, the
+  # command, and any environment variables written into the
+  # definition itself in plain text. Values injected from Secrets
+  # Manager or Parameter Store are named there rather than resolved,
+  # so what comes back is the reference and not the secret.
+  - Sid: EcsInventory
+    Effect: Allow
+    Action:
+      - ecs:DescribeCapacityProviders
+      - ecs:DescribeClusters
+      - ecs:DescribeContainerInstances
+      - ecs:DescribeServices
+      - ecs:DescribeTaskDefinition
+      - ecs:DescribeTasks
+      - ecs:ListClusters
+      - ecs:ListContainerInstances
+      - ecs:ListServices
+      - ecs:ListTagsForResource
+      - ecs:ListTaskDefinitionFamilies
+      - ecs:ListTaskDefinitions
+      - ecs:ListTasks
+    Resource: "*"
+
+  - Sid: LambdaInventory
+    Effect: Allow
+    Action:
+      - lambda:GetFunctionConfiguration
+      - lambda:GetPolicy
+      - lambda:ListAliases
+      - lambda:ListFunctions
+      - lambda:ListTags
+      - lambda:ListVersionsByFunction
+    Resource: "*"
+
+  # lambda:GetFunction returns a pre-signed URL to the deployment
+  # package. That is source-code access, so it is denied outright.
+  - Sid: NeverDownloadFunctionCode
+    Effect: Deny
+    Action:
+      - lambda:GetFunction
+      - lambda:GetLayerVersion
+    Resource: "*"
+```
+
+## How Kosli isolates customers
+
+Kosli Capture runs as a shared, autoscaled service, but each job runs under a role that is scoped to
+one customer:
+
+* A Kosli Capture worker picks up a job for your organization and assumes a Kosli-side role that
+  exists only for your organization. Only that role is permitted to call AssumeRole into your
+  account with your ExternalId. A Kosli Capture worker running for a different customer is unable
+  to connect to your cloud account.
+* When the job finishes, those credentials are discarded. A worker holding credentials for your
+  cloud account has no path to anyone else's account.
+* The ExternalId lives in Parameter Store and is readable only by the Kosli-side role for your
+  organization. The shared task role cannot read any customer's ExternalId. Separation is enforced
+  by IAM, not by application code.
+
+The trust policy on the role in your account limits access to the AWS account in which Kosli
+Capture is running. The ExternalId acts as a shared secret between Kosli and you, so that only
+Kosli Capture is permitted to assume the role.
+
+Kosli Capture itself does not hold any customer data. Snapshots taken by Kosli Capture are
+immediately sent to Kosli through the same ingest path as your existing pipelines.

administration/managing_environments/overview.md

@@ -64,6 +64,10 @@ terraform import kosli_environment.my_environment production
 The `type` in your Terraform configuration must exactly match the type of the existing environment in Kosli. A mismatch will cause import errors or misconfiguration.
 </Warning>
 
+### Automatically creating physical environments
+
+[Kosli Capture Managed Service](/administration/kosli_capture/overview) snapshots the supported resources it finds in your cloud accounts and creates physical environments as needed.
+
 ## Managing logical environments
 
 Logical environments group physical environments into a combined view — useful for representing a full production tier across multiple runtimes.

config/navigation.json

@@ -73,7 +73,15 @@
                 "administration/managing_custom_attestation_types/overview"
               ]
             },
-            "administration/managing_tags"
+            "administration/managing_tags",
+            {
+              "group": "Kosli Capture",
+              "pages": [
+                "administration/kosli_capture/overview",
+                "administration/kosli_capture/getting_started",
+                "administration/kosli_capture/security"
+              ]
+            }
           ]
         },
         {

getting_started/environments.md

@@ -55,7 +55,7 @@ Currently, the following environment types are supported:
 - Azure Web Apps and Function Apps
 - Google Cloud Run (services and jobs)
 
-You can report environment snapshots manually using the `kosli snapshot [...]` commands for testing. For production use, however,  you would configure the reporting to happen automatically on regular intervals, e.g. via a cron job or scheduled CI job, or on certain events.
+You can report environment snapshots manually using the `kosli snapshot [...]` commands for testing. For production use, however, you would configure the reporting to happen automatically on regular intervals, e.g. via a cron job or scheduled CI job, or on certain events. Kosli can also report these snapshots for you, using the [Kosli Capture Managed Service](/administration/kosli_capture/overview).
 
 You can follow one of the tutorials below to setup automatic snapshot reporting for your environment:
 - [Kubernetes environment reporting](/tutorials/report_k8s_envs)