> ## Documentation Index
> Fetch the complete documentation index at: https://kosli-kosli-capture-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Kosli Capture - Security

> Learn about the security of Kosli Capture

<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 theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
  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 theme={"theme":"dracula","languages":{"custom":["/languages/rego.json"]}}
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.