docs: add Kosli Capture Managed Service page

administration/kosli_capture/overview.md

@@ -0,0 +1,73 @@
+---
+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: "ALPHA"
+---
+
+<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.
+
+## Overview
+
+Kosli Capture connects to your cloud accounts using permissions that you manage.  You configure Kosli Capture by providing a few details describing what you want to be in scope, and Kosli Capture uses the permissions to regularly reach into your estate and record snapshots, sending the data into your Kosli organization.  Kosli Capture is architected to be driven by your tagging scheme; it examines the tags on your infrastructure and uses them to determine how to structure the snapshots, and how to build the environments within Kosli.
+
+There are several benefits to this this architecture:
+
+* the only infrastructure you need to manage is an IAM role; you do not need to install or execute any additional software in your cloud estate;
+* Kosli Capture leverages your existing tagging scheme, so as your infrastructure evolves, Kosli Capture will automatically discover the snapshots it needs to take.
+
+## Security
+
+The security of your cloud infrastructure is the primary driver behind the internal architecture of the Kosli Capture managed service.  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 A's account with A's ExternalId.
+* 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 trust policy's 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.
+
+Kosli Catpure does not hold any customer data, it is near-stateless with the only thing it keeps is your configuration data.  Snapshots taken by Kosli Catpure are immediately sent to Kosli through the same ingest path as your existing pipelines.
+
+## 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 handed automatically.  As your cloud infrastructure changes over time, Kosli capture will continue to find resources according to your tagging scheme 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.
+
+## Setup
+
+Getting started with Kosli Capture involves three 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 during onboarding.
+  </Step>
+  <Step title="Write the configuration document">
+    Working with Kosli's Customer Success team, author a configuration document that shows how your cloud resources should be mapped to Kosli environments. This configuration document is loaded into Kosli.
+  </Step>
+  <Step title="Enable Kosli Capture">
+    Kosli enables Kosli Capture for your Kosli org, and the regular snapshots appear in Kosli.
+  </Step>
+</Steps>
+
+## Finding resources
+
+Kosli Capture finds all supported resources within your AWS accounts, and examines the tags on those resources to determine which Kosli environment should hold the snapshots. Kosli Capture will create physical environments for you.
+
+Kosli Capture can filter out resources based on your tags.
+
+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 configuration document.
+
+## IAM permissions
+
+For Kosli Capture to snapshot your environment, you must grant a set of read-only permissions. Kosli's CloudFormation template lists these. The permissions are typically "Describe" or "List" permissions.  The [Kosli Capture Security](/administration/kosli_capture/security) page provides a deep-diver into the structure of the permissions needed.
+
+The IAM role created in your environment includes a trust policy that allows Kosli Capture to assume the role. The trust policy limits access to the AWS account in which Kosli Capture is running. Furthermore, the trust policy includes an external ID that acts as a shared secret between Kosli and you, so that only access from Kosli Capture is permitted.
+
+The external ID (shared secret) is securely stored with Kosli Capture. Kosli's internal IAM permissions ensure that the secret can only be accessed by the specific instance of Kosli Capture worker that is operating for you.

administration/kosli_capture/security.md

@@ -0,0 +1,100 @@
+---
+title: Kosli Capture - Security
+sidebarTitle: Security
+description: "Learn about the security of Kosli Capture"
+tag: "ALPHA"
+---
+
+<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, GCP and Azure 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.
+
+### Assume role
+
+The IAM role defined within the CloudFormation template includes an "assume role" policy granting permission from Kosli.  This appears as:
+
+```
+  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:
+
+```
+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; those tags are what decide which
+  # Kosli environment a cluster is reported into. Without
+  # ListClusters and DescribeClusters a role created from this
+  # template cannot run discovery at all.
+  #
+  # 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: "*"
+````

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
+
+The [Kosli Capture Managed Service](/administration/kosli_capture/overview) will automatically snapshot your infrastructure according to rules you define. Kosli Capture will create 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

@@ -72,7 +72,14 @@
                 "administration/managing_custom_attestation_types/overview"
               ]
             },
-            "administration/managing_tags"
+            "administration/managing_tags",
+            {
+              "group": "Kosli Capture",
+              "pages": [
+                "administration/kosli_capture/overview",
+                "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)