---
title: "Introducing CloudGrappler: A Powerful Open-Source Threat Detection Tool for Cloud Environments"
description: CloudGrappler is an open-source tool that is purpose-built for querying high-fidelity and single-event detections related to well-known threat actors in popular cloud environments such as AWS and Azure.
---

[Latest research, product updates and best practices on staying secure in the cloud | Permiso ](https://permiso.io/blog)

# [Introducing CloudGrappler: A Powerful Open-Source Threat Detection Tool for Cloud Environments](https://permiso.io/blog/cloudgrappler-a-powerful-open-source-threat-detection-tool-for-cloud-environments)

 Written by [Andi Ahmeti](https://permiso.io/blog/author/andi-ahmeti) | Mar 7, 2024 1:37:48 PM

**Introduction  
**  
With the increased activity of threat actor groups like [LUCR-3](https://permiso.io/blog/lucr-3-scattered-spider-getting-saas-y-in-the-cloud) (Scattered Spider) over the last year, being able to detect the presence of these threat groups in cloud environments continues to present a significant challenge to most security teams. While we have shared a lot of tips on detecting and hunting for cloud threat actors in previous [blogs](https://permiso.io/blog/s/unmasking-guivil-new-cloud-threat-actor/) and [briefings](https://permiso.io/blog/permiso-offers-complimentary-threat-briefings-on-scattered-spider), we wanted to take it a step further and offer teams an open-source tool that will help them detect these threat actors in their cloud environments.

**Introducing CloudGrappler**

CloudGrappler is an open-source tool that is purpose-built for querying high-fidelity and single-event detections related to well-known threat actors in popular cloud environments such as AWS and Azure. Leveraging the capabilities of [cloudgrep](https://github.com/cado-security/cloudgrep), developed by Cado Security, the tool queries activity in cloud environments that match known Tactics, Techniques, and Procedures (TTPs) of modern cloud threat actor groups. It’s like a cyber detective for activity in your AWS and Azure environments to find suspicious and malicious activity that are often missed or ignored in a flood of alerts.

## Key Features

#### **Threat Actor Querying **

**CloudGrappler **specializes in querying for activity demonstrated by some of the most notorious threat actors in the cloud. Based on subset activity from Permiso’s library of hundreds of detection, It helps organizations detect threats targeting their cloud infrastructure.

#### **Single-Event Detections**

This open-source tool excels in detecting and analyzing single events and offers a granular view of potential security incidents lurking in your AWS and Azure environments. This gives security teams the ability to identify specific anomalies quickly and easily.

#### **Integration with cloudgrep**

Leveraging the robust capabilities of [cloudgrep](https://github.com/cado-security/cloudgrep), CloudGrappler enhances its threat detection by incorporating a set of TTPs observed in the modern threat landscape and actual cloud environments.

## How **CloudGrappler** Works

### Scope Selector 

CloudGrappler features an integrated `data_sources.json` file that provides users with an easy-to-use interface to define the scope of their scanning. Within this file, users can specify the parameters for what and where they want to scan or have the option to do a comprehensive scan across both AWS and Azure environments. Users have the ability to scan specific resources within their environment or cast a wider net to include a broader range of cloud infrastructure services. Scan as little or as much as you want.

### Query Selector

**CloudGrappler** includes a `queries.json` file which includes predefined TTPs commonly used by threat actors. Each line in the `queries.json` file includes the query's name, its source (AWS or AZURE), and a source modifier. Users can modify the source to a wildcard character (*) to scan the corresponding query across both AWS and Azure environments. Furthermore, users have the ability to add custom queries to the file or scan across other, multiple files.

### Report Generator

Upon completion of the scanning process, **CloudGrappler** delivers a comprehensive report in a JSON format. The report hierarchically provides a detailed breakdown of the scan results. The hierarchy includes information such as the cloud platform (e.g., AWS), timestamp (2024-01-08 01:38 AM), specific resources (e.g., test-bucket), and additional details like prefixes or filenames (e.g., prefix/GetFileDownloadUrls.*secrets_json). These reports offer a easy to read, granular details of the findings to enable security team to address them as quickly as possible.

# Use Examples

### Help -h

|   python3 main.py -h

> usage: main.py [-h] [-jo] [-f ADD_FILE] [-p] [-q QUERY] [-s SOURCE_TYPE] [-sd START_DATE] [-ed END_DATE] [-fs FILE_SIZE]
> 
> Process data.
> 
> options:  
>   -h, --help                      Show this help message and exit  
>   -jo, --json_output    Write output to a json file.  
>   -f ADD_FILE, --add_file ADD_FILE  
>                                               Add new queries json file.  
>   -p, --permiso_intel  Output permiso intel.  
>   -q QUERY, --query QUERY  
>                                               Add query/ies  
>   -s SOURCE_TYPE, --source_type SOURCE_TYPE  
>                                               Add source type to query for  
>   -sd START_DATE, --start_date START_DATE  
>                                                Optionally filter on Objects modified after a Date or Time. E.g. 2022-01-01  
>   -ed END_DATE, --end_date END_DATE  
>                                                Optionally filter on Objects modified before a Date or Time. E.g. 2022-01-01  
>   -fs FILE_SIZE, --file_size FILE_SIZE  
>                                                Optionally filter on Objects smaller than a file size, in bytes. Defaults to 100 MB. 

## **Querying for Threat Activity**

Before being able to scan your environment, you will need to first define the scope of what you will be scanning in the `data.sources.json` file. Users have the flexibility to define the scope based on their specific cloud infrastructure configuration. The following example showcases a structured `data_sources.json` file for both AWS and Azure environments:

|   python3 main.py 

## **Gather Threat Intelligence**

In addition to detecting suspicious and malicious activity in your environment CloudGrappler output provides teams with additional intelligence based on the events it’s detecting to provide teams with a deeper understanding of the potential risk in their environment.

This additional context provides security professionals with threat intelligence for modern to advanced threat actors and helps them develop more comprehensive targeted response strategies.****

- -p ⇒ permiso_intel

|   python3 main.py -p

> [+] Running GetFileDownloadUrls.*secrets_ for AWS   
> [+] Threat Actor: LUCR3   
> [+] Severity: MEDIUM   
> [+] Description: Review use of CloudShell. Permiso seldom witnesses use of CloudShell outside of known attackers.This however may be a part of your normal business use case. 
> 
> ------------------------------------------------------------------------------------------------------------------------------  
> [+] Running s3_secret for AZURE   
> [+] TTP: LUCR3   
> [+] Severity: MEDIUM   
> [+] Description: Typical query searched by LUCR3 Threat Actor 
> 
> ------------------------------------------------------------------------------------------------------------------------------  
> [+] Running DisassociateFromMasterAccount for AWS   
> [+] Threat Actor: LUCR3   
> [+] Severity: MEDIUM   
> [+] Description: An attacker exploiting the DisassociateFromMasterAccount eventName might gain unauthorized access, escalate privileges, disrupt operations, manipulate or steal data, and potentially impersonate legitimate entities within the system. 
> 
> ------------------------------------------------------------------------------------------------------------------------------  
> [+] Running EnableSerialConsoleAccess for AWS   
> [+] Threat Actor: LUCR3   
> [+] Severity: MEDIUM   
> [+] Description: An attacker could potentially leverage 'EnableSerialConsoleAccess' to bypass regular security measures and gain unauthorized entry or control over a system through direct access to its serial console.

*(Snippet from running the tool with Permiso threat intel provided)*

#### **Filtering logs based on date or time**

You can filter on Objects modified before or after a specified date or time

- -sd ⇒ START_DATE
- -ed ⇒ END_DATE

|   python3 main.py -p -sd 2024-02-15 -ed 2024-02-16

#### **Adding custom queries and data source types**

CloudGrappler provides the ability to add custom queries and data sources to scan for.

In this example we’re scanning for two queries and appending the wild character inside the source type. This means the tool will check for hits on both cloud environments specified in the data_source.json file.

- -q ⇒ QUERY
- -s ⇒ SOURCE_TYPE

|   python3 main.py -q “GetFileDownloadUrls.*secret”, ”UpdateAccessKey” -s ‘ * ‘

#### **Generate Reports**

Below is an example of the report generated in a json format containing the scan results and Permiso’s intel related to those events.

- -p ⇒ permiso_intel
- -jo ⇒ json_output

|   python3 main.py -p -jo

> reports  
> └── json  
>     ├── AWS  
>     │   └── 2024-01-16 01:01 AM  
>     │       └── aws-cloudtrail-logs--  
>     │           └── testTrails_AWSLogs  
>     │               └── GetFileDownloadUrls.*secrets_.json  
>     └── AZURE  
>         └── 2024-01-16 01:01 AM  
>             └── storagetest  
>                 └── cloudgrepping  
>                     └── andi.ahmeti@permiso.io.json

You can get CloudGrappler on GitHub: [https://github.com/Permiso-io-tools/CloudGrappler](https://github.com/Permiso-io-tools/CloudGrappler) 

[View full post](https://permiso.io/blog/cloudgrappler-a-powerful-open-source-threat-detection-tool-for-cloud-environments)

```json
{
  "@context" : "http://schema.org",
  "@type" : "BlogPosting",
  "author" : {
    "@type" : "Person",
    "name" : "Andi Ahmeti"
  },
  "dateModified" : "2024-04-18T11:22:09.620Z",
  "datePublished" : "2024-03-07T13:37:48Z",
  "headline" : "Introducing CloudGrappler: A Powerful Open-Source Threat Detection Tool for Cloud Environments",
  "image" : {
    "@type" : "ImageObject",
    "height" : 596,
    "url" : "https://20407698.fs1.hubspotusercontent-na1.net/hubfs/20407698/Cloud-Grappler.png",
    "width" : 1784
  },
  "mainEntityOfPage" : "https://permiso.io/blog/cloudgrappler-a-powerful-open-source-threat-detection-tool-for-cloud-environments",
  "publisher" : {
    "@type" : "Organization",
    "logo" : {
      "@type" : "ImageObject",
      "height" : 60,
      "url" : "/hs/hsstatic/content_shared_assets/static-1.4092/img/default-amp-logo.png",
      "width" : 60
    },
    "name" : "Cloud Chronicles"
  }
}
```