# Log Source Management (Beta)

## Overview

{% hint style="info" %}
Log source management API operations are in open beta starting with Panther version 1.72. Please share any bug reports and feature requests with your Panther support team.
{% endhint %}

The Panther API supports the following log source operations:

* Listing your log source integrations
* Fetching the details of a particular log source integration
* Deleting a log source integration
* (For S3 sources only) Creating a new log source integration
* (For S3 sources only) Updating an existing log source integration

{% hint style="info" %}
The `ListSources`, `GetSource`, and `DeleteSource` operations are supported for any log source in Panther. The create and update operations (`CreateS3LogSource` and `UpdateS3LogSource`) are currently limited to only S3 log sources.
{% endhint %}

You can invoke Panther's API by using your Console's API Playground, or the GraphQL-over-HTTP API. Learn more about these methods on [Panther API](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/panther-developer-workflows/api/..#step-1-choose-a-method-for-invoking-the-api).

### Required API token permissions

Before starting to make API calls, ensure your API token has the necessary permissions attached:

* **View Log Sources**: Required for all log source management operations.
* **Manage Log Sources**: Required for the log source management operations that are mutations (i.e., `CreateS3LogSource`, `UpdateS3LogSource`, and `DeleteSource`).
* **Read User Info**: Required if you would like to retrieve integration fields related to an actor, such as `createdBy`.

<figure><img src="https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fqj6uxBNk2aLvwv5ViMfh%2FScreenshot%202023-06-12%20at%203.45.48%20PM.png?alt=media&#x26;token=16271364-6713-4413-9a77-221f209a1eee" alt="" width="563"><figcaption></figcaption></figure>

## Common log source operations

Below are some of the most common GraphQL log source operations in Panther. These examples demonstrate the documents you have to send using a GraphQL client (or `curl`) to make a call to Panther's GraphQL API.&#x20;

#### Listing log sources

{% hint style="info" %}
Pagination is not currently supported by `sources`—all log sources will be returned in the first page of results. The `cursor` field in the `input` object, below, is a placeholder for when pagination is eventually supported.
{% endhint %}

```graphql
query ListSources {
  sources(input: { cursor: "" }) {
    edges {
      node {
        createdAtTime
        createdBy {
          ... on User {
            id
          }
          ... on APIToken {
            id
          }
        }
        integrationId
        integrationLabel
        integrationType
        isEditable
        isHealthy
        lastEventProcessedAtTime
        lastEventReceivedAtTime
        lastModified
        logTypes
      }
    }
    pageInfo {
      endCursor
      hasNextPage
      hasPreviousPage
      startCursor
    }
  }
}
```

#### Retrieving a log source

The input to `source` is the ID of the log source you'd like to fetch.

```graphql
query GetSource {
  source(id: "bcd45662-bab7-4f99-b69f-083a0212568d") {
    createdAtTime
    createdBy {
      ... on User {
        id
      }
      ... on APIToken {
        id
      }
    }
    integrationId
    integrationLabel
    integrationType
    isEditable
    isHealthy
    lastEventProcessedAtTime
    lastEventReceivedAtTime
    lastModified
    logTypes
  }
}
```

#### Deleting a log source

The input to `deleteSource` is the ID of the log source you'd like to delete.

```graphql
mutation DeleteSource {
  deleteSource(input: { id: "bcd45662-bab7-4f99-b69f-083a0212568d" }) {
    id
  }
}
```

#### Creating an S3 log source

{% hint style="info" %}
It's also possible to create a S3 log source [using Terraform](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/panther-developer-workflows/terraform/s3), or [manually in the Panther Console](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/data-onboarding/data-transports/aws/s3).
{% endhint %}

In the example request below, `input` is an object that fully represents your S3 log source. All fields shown are required.

The value of `logProcessingRole` is the ARN of an IAM role. When creating this role, take note of [these guidelines](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/data-onboarding/data-transports/aws/s3#i-want-to-set-everything-up-on-my-own), which describe which policies must be attached.

```graphql
mutation CreateS3LogSource {
  createS3Source(
    input: {
      awsAccountId: "0123456789012"
      label: "My Log Source"
      logProcessingRole: "arn:aws:iam::0123456789012:role/PantherLogProcessingRole-somerole"
      logStreamType: JSON
      managedBucketNotifications: false
      s3Bucket: "name-of-my-bucket"
      s3PrefixLogTypes: [
        { excludedPrefixes: [], logTypes: ["AWS.ALB"], prefix: "" }
      ]
    }
  ) {
    logSource {
      createdAtTime
      integrationId
      integrationLabel
      integrationType
      isEditable
      isHealthy
      lastEventProcessedAtTime
      lastEventReceivedAtTime
      lastModified
      logTypes
    }
  }
}
```

#### Updating an S3 log source

In the example request below, `input` is an object that fully represents your updated S3 log source. All fields shown are required, as `updateS3Source` replaces all fields of the existing log source (rather than only updating specific fields).

```graphql
mutation UpdateS3LogSource {
  updateS3Source(
    input: {
      id: "bcd45662-bab7-4f99-b69f-083a0212568d"
      label: "My Log Source2"
      kmsKey: ""
      logProcessingRole: "arn:aws:iam::0123456789012:role/PantherLogProcessingRole-somerole"
      logStreamType: JSON
      managedBucketNotifications: false
      s3PrefixLogTypes: [
        { excludedPrefixes: [], logTypes: ["AWS.ALB"], prefix: "" }
      ]
    }
  ) {
    logSource {
      createdAtTime
      integrationId
      integrationLabel
      integrationType
      isEditable
      isHealthy
      lastEventProcessedAtTime
      lastEventReceivedAtTime
      lastModified
      logTypes
    }
  }
}
```