# Log Source Management

## Overview

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/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%2Fgit-blob-4692296563f124328e000bab991e05d423db5e2b%2FScreenshot%202023-06-12%20at%203.45.48%20PM.png?alt=media" alt="An &#x22;Integrations&#x22; header is above four checkboxes: View Cloud Security Sources, Manage Cloud Security Sources, View Log Sources, and Manage Log Sources." 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.

#### 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/panther-developer-workflows/terraform/s3), or [manually in the Panther Console](https://docs.panther.com/data-onboarding/data-transports/aws/s3).
{% endhint %}

{% hint style="warning" %}
The first log source you create in Panther must be done in the Panther Console. If you use the API to set up your first Panther log source, you may run into a "pending confirmation" issue detailed in [this Knowledge Base article](https://help.panther.com/articles/2327494518-why-is-my-sns-topic-stuck-in-a-pending-confirmation-state-for-the-sqs-confirmation-for-panther).
{% 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/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
    }
  }
}
```