Skip to main content

Set up AWS for Live Search and runLiveSearchQuery

To upload the results of a live search to an S3 bucket, You need to set up your AWS (Amazon Web Services) cloud platform in advance. This includes creating an IAM role, configuring the target bucket, and defining the necessary access policies.

The process relies on cross-account access, where Bitdefender assumes the user-provided role within AWS to securely upload the results to the designated S3 (Simple Storage Service) bucket. To configure AWS, follow these steps:

  1. Log in to your AWS cloud platform.

  2. Create the S3 bucket. Go to Amazons S3 > Buckets > Create bucket and create an S3 bucket.

    Note

    For more information on this process, refer to this KB article.

    The information stored in the bucket will be saved in the following path: <companyId>/<endpointProtectedEntityId>/osquery_<endpointProtectedEntityId>_<date>.json.

    Variable

    Description

    companyId

    The ID of the GravityZone company.

    endpointProtectedEntityId

    The ID of the protected entity representing the endpoint.

    date

    The date when the live search task was created.

  3. Create an AWS role to provide GravityZone with the required permissions to upload files to the bucket. Go to IAM > Roles > Create role.

    Note

    For more information on creating roles, refer to this Amazon KB article.

    In the creation form select Custom trust policy and add a trust policy that has the following format:

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Allow",
            "Principal": {
                "AWS": arn:aws:iam::789423628920:root
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": <externalId>
                }
            }
        }
    ]
}

    This trust policy grants permission for the Bitdefender user to assume the role. Here, the Principal.AWS field specifies the Amazon Resource Name (ARN) of the Bitdefender user, defining who is allowed to assume the role.

    For enhanced security, the ExternalId should also be configured. This is a custom string that helps prevent unauthorized access. The value can be any unique identifier and will be passed as a parameter when invoking the runLiveSearchQuery method via the API.

  4. Add a bucket policy. Go back to the bucket and then go to Permissions. Add the following bucket policy:

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Allow",
            "Principal": {
                "AWS": <roleArn>
            },
            "Action": "s3:PutObject",
            "Resource": <bucketArn>
        }
    ]
}

    Parameter

    Description

    Principal.AWS

    The Amazon Resource Name (ARN) of the IAM role that will access the bucket.

    For example: "arn:aws:iam::205620608461:role/osquery-role".

    Resource

    the ARN of the S3 bucket and its objects, defining what the policy applies to.

    For example: "arn:aws:s3:::osquery-bucket-test/*".

    Note

    For more information on bucket policies, refer to this Amazon KB article.

    This policy allows the role to put objects in the S3 bucket.

  5. Create a policy for the role. Go to IAM > Policies > Create policy.

    Create the following policy:

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": "s3:PutObject",
            "Resource": <bucketArn>
        }
    ]
}

    This policy grants the role permission to execute the PutObject action on the specified S3 bucket.

    The Resource field defines the ARN of the target bucket, specifying where the role is allowed to upload objects. For example, "arn:aws:s3:::osquery-bucket-test/*".

  6. Make a request using the runLiveSearchQuery:

    {
    "params": {
        "companyId": <companyId>,
        "query": "select * from time;",
        "s3UploadConfig": {    
            "bucket": <bucketName>,
            "region": <bucketRegion>,
            "roleArn" : <roleArn>,
            "externalId" : <externalId>
        }
    },
    "jsonrpc": "2.0",
    "method": "runLiveSearchQuery",
    "id": "301f7b05-ec02-481b-9ed6-c07b97de2b7b"
}

    Example

    {
    "params": {
        "companyId": <companyId>,
        "query": "select * from time;", // or any other live search query
        "s3UploadConfig": {    
            "bucket": "osquery-bucket-test",
            "region": "eu-north-1",
            "roleArn": "arn:aws:iam::205620608461:role/osquery-role",
            "externalId": "12345678910"
        }
    },
    "jsonrpc": "2.0",
    "method": "runLiveSearchQuery",
    "id": "301f7b05-ec02-481b-9ed6-c07b97de2b7b"
}

    Note

    For more information on this method, refer to the runLiveSearchQuery document.

  7. If your endpoints are communicate with GravityZone through a Relay and cannot reach the S3 bucket, you need to whitelist the bucket's domain in the Relay's policy settings.To do this, follow these steps:

    1. Go to the Network > Policies page in the GravityZone console, and open the policy applied to the endpoints in question.

    2. Go to Policy > General > Relay > Communication.

    3. Under the Whitelisted domains for API data section, add the domain of the S3 bucket (for example, s3<region>amazonaws.com) to the Domain field.

    4. Select the Plus button to add the domain.

    5. Select Save.

    This will allow traffic to and from the bucket.

In this section: