### Install gremlin-python from source

Source: https://github.com/gremlin/gremlin-python/blob/main/README.md

Clone the repository and install the SDK locally from the source code.

```bash
git clone git@github.com:gremlin/gremlin-python.git
cd gremlin-python
pip3 install .
```

--------------------------------

### Install gremlin-python via PyPI

Source: https://github.com/gremlin/gremlin-python/blob/main/README.md

Use this command to install the gremlin-python SDK using pip.

```bash
pip3 install gremlinapi
```

--------------------------------

### Create a Gremlin Scenario Graph

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/scenarios.md

Illustrates building a scenario graph with status checks, delays, and iterative latency attacks. Requires API key and team GUID configuration.

```python
from gremlinapi.config import GremlinAPIConfig as config
from gremlinapi.attack_helpers import GremlinBlackholeAttack, GremlinLatencyAttack, GremlinTargetContainers
from gremlinapi.scenario_graph_helpers import (
    GremlinScenarioGraphHelper,
    GremlinScenarioILFINode,
    GremlinScenarioDelayNode,
    GremlinScenarioStatusCheckNode
)
from gremlinapi.scenarios import GremlinAPIScenarios as scenarios

my_api_key = "123...xyz"
my_team_guid = 'uuid'

config.api_key = my_api_key
config.team_guid = my_team_guid

description = f'This is a test scenario to illustrate the usage of the new scenario graph model'
hypothesis = f'This should create a functional scenario with multiple attack iterations and a status_check'

blast_radius_steps = [50, 100]  # Percents
latency_magnitude_steps = [100, 500, 1000]  # Latency in milliseconds
delay_time = 5 # Time to delay between steps in seconds

# Status check config
status_check_description="Check if Gremlin.com is Still Up"

endpoint_url = 'https://www.gremlin.com'
endpoint_headers = dict()

# Optionally you can set specific header attributes
# status_check_api_key = 'Key foo...'
# endpoint_headers = {
#     'Authorization': status_check_api_key
# }

evaluation_ok_status_codes = ['200-203', '210']
evaluation_ok_latency_max = 500
evaluation_response_body_evaluation = {
    "op": "AND",
    "predicates": []
}

my_scenario = GremlinScenarioGraphHelper(name='test_scenario_1', description=description, hypothesis=hypothesis)

# Add the status check to the start of the scenario
status_check_node = GremlinScenarioStatusCheckNode(
    description=status_check_description,
    endpoint_url=endpoint_url,
    endpoint_headers=endpoint_headers,
    evaluation_ok_status_codes=evaluation_ok_status_codes,
    evaluation_ok_latency_max=evaluation_ok_latency_max,
    evaluation_response_body_evaluation=evaluation_response_body_evaluation
)
my_scenario.add_node(status_check_node)

# Add a delay step between the status check and the attacks
delay_node = GremlinScenarioDelayNode(delay=delay_time)

#adds node to graph
my_scenario.add_node(delay_node)

#adds edge
my_scenario.add_edge(status_check_node, delay_node)

# Add latency attacks to the scenario
for magnitude_idx, magnitude in enumerate(latency_magnitude_steps):
    for blast_radius_idx, blast_radius in enumerate(blast_radius_steps):
        print(f'Blast radius {blast_radius_idx+1} of {len(blast_radius_steps)} :: {blast_radius}%')
        print(f'Magnitude {magnitude_idx+1} of {len(latency_magnitude_steps)} :: {magnitude}ms')
        new_node = GremlinScenarioILFINode(
            command=GremlinLatencyAttack(delay=magnitude),
            target=GremlinTargetContainers(strategy_type='Random', labels={'owner': 'kyle'}, percent=blast_radius)
        )
        # Passing True as the second variable adds an edge from the last node in the graph to the 
        # node being added
        my_scenario.add_node(new_node, True)
        # Add a delay step between attacks, skip this if it's the last step in the loop
        if not ((magnitude_idx+1 == len(latency_magnitude_steps)) and (blast_radius_idx+1 == len(blast_radius_steps))):
            my_scenario.add_node(GremlinScenarioDelayNode(delay=delay_time), True)

# Let's view the json output
print(my_scenario)

# Send the scenario to Gremlin
my_scenario_guid = scenarios.create_scenario(body=my_scenario)

```

--------------------------------

### Get Company Details

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/companies.md

Retrieve specific details for a given company using its identifier. Ensure you have the correct company GUID.

```python
from gremlinapi.companies import GremlinAPICompanies as companies

company_id = 'COMPANY_GUID'
response = companies.get_company(identifier=company_id)
```

--------------------------------

### Targeting Hosts and Containers

Source: https://context7.com/gremlin/gremlin-python/llms.txt

Define specific targeting strategies for hosts and containers using Gremlin's targeting classes. These examples show exact host matching and random container selection based on labels.

```python
tagged_hosts = GremlinTargetHosts(
    strategy_type="exact",
    exact=2,
    target_all_hosts=False,
    tags={"os-type": "Linux"}
)
```

```python
tagged_containers = GremlinTargetContainers(
    strategy_type="random",
    percent=25,
    target_all_containers=False,
    labels={"app": "payment-service", "env": "staging"}
)
```

```python
import json
print(json.dumps(tagged_containers.api_model(), indent=2))
```

--------------------------------

### Activate Gremlin Client

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/clients.md

Use this to activate a specific Gremlin client. Requires the client's GUID and the team ID.

```python
from gremlinapi.clients import GremlinAPIClients as clients
team_id = 'TEAM_ID'
client_guid = 'CLIENT_GUID'

response = clients.activate_client(guid=client_guid, teamId=team_id)
```

--------------------------------

### Get ALFI Experiment Details

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/alfi.md

Retrieve detailed information about a specific ALFI experiment using its GUID. Requires the `gremlinapi.alfi` module.

```python
from gremlinapi.alfi import GremlinALFI as alfi
from pprint import pprint

alfi_attack_id = 'expirment-guid'
experiment_details = alfi.get_alfi_experiment_details(guid=alfi_attack_id)

pprint(experiment_details)
```

--------------------------------

### Get Attack Details

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/attacks.md

Retrieves detailed information about a specific attack using its GUID and team ID. Requires importing GremlinAPIAttacks.

```python
from gremlinapi.attacks import GremlinAPIAttacks as attacks
team_id = 'TEAM_ID/UUID'
attack_id = 'ATTACK_ID'
attack_details = attacks.get_attack(guid=attack_id, teamId=team_id)

from pprint import pprint
pprint(attack_details)
```

--------------------------------

### Activate Client

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/clients.md

Activates a specific client using its GUID and the team ID.

```APIDOC
## Activate Client

### Description
Activates a specific client.

### Method
POST (inferred from typical API patterns for activation)

### Endpoint
/clients/{guid}/activate (inferred)

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier of the client to activate.

#### Query Parameters
- **teamId** (string) - Required - The ID of the team the client belongs to.

### Request Example
```python
from gremlinapi.clients import GremlinAPIClients as clients
team_id = 'TEAM_ID'
client_guid = 'CLIENT_GUID'

response = clients.activate_client(guid=client_guid, teamId=team_id)
```

### Response
#### Success Response (200)
Details of the activated client (schema not provided in source).
```

--------------------------------

### Build Gremlin Scenarios with Graph Nodes

Source: https://context7.com/gremlin/gremlin-python/llms.txt

Construct complex attack scenarios using GremlinScenarioGraphHelper. Add nodes like ILFI attacks, delays, and status checks, then connect them to define the scenario flow. Requires GremlinAPIConfig setup.

```python
from gremlinapi.config import GremlinAPIConfig as config
from gremlinapi.scenarios import GremlinAPIScenarios as Scenarios
from gremlinapi.scenario_graph_helpers import (
    GremlinScenarioGraphHelper,
    GremlinScenarioILFINode,
    GremlinScenarioDelayNode,
    GremlinScenarioStatusCheckNode,
)
from gremlinapi.attack_helpers import (
    GremlinCPUAttack,
    GremlinLatencyAttack,
    GremlinTargetHosts,
)

config.api_key = "Key MU3...ZiTk...Lo...4zO..c="
config.team_id = "e7352a6b-a9a0-513c-81e4-980f680a70c4"

# Create the scenario container
scenario = GremlinScenarioGraphHelper(
    name="CPU Ramp Test",
    description="Gradually increase CPU load and verify auto-scaling",
    hypothesis="Service remains healthy as CPU scales up; instances scale out"
)

# Create nodes
cpu_low = GremlinScenarioILFINode(
    command=GremlinCPUAttack(length=60, capacity=30, all_cores=True),
    target=GremlinTargetHosts(strategy_type="random", percent=50)
)
delay1 = GremlinScenarioDelayNode(delay=10)
health_check = GremlinScenarioStatusCheckNode(
    description="Verify service responds",
    endpoint_url="https://service.internal/health",
    endpoint_headers={"Authorization": "Bearer healthtoken"},
    evaluation_ok_status_codes=["200"],
    evaluation_ok_latency_max=300
)
cpu_high = GremlinScenarioILFINode(
    command=GremlinCPUAttack(length=60, capacity=80, all_cores=True),
    target=GremlinTargetHosts(strategy_type="random", percent=50)
)

# Add nodes — the first added becomes HEAD
scenario.add_node(cpu_low)
scenario.add_node(delay1)
scenario.add_node(health_check)
scenario.add_node(cpu_high)

# Connect linearly: cpu_low → delay1 → health_check → cpu_high
scenario.add_edge(delay1, cpu_low)
scenario.add_edge(health_check, delay1)
scenario.add_edge(cpu_high, health_check)

# Submit to Gremlin API
result = Scenarios.create_scenario(body=scenario, teamId=config.team_id)
print(f"Created scenario: {result['guid']}")
```

--------------------------------

### Target 50% of all active hosts with GremlinTargetHosts

Source: https://context7.com/gremlin/gremlin-python/llms.txt

Use GremlinTargetHosts to select infrastructure for attacks. This example targets 50% of all active hosts using a random strategy.

```python
from gremlinapi.attack_helpers import GremlinTargetHosts, GremlinTargetContainers

# Target 50% of all active hosts
all_hosts_50pct = GremlinTargetHosts(strategy_type="random", percent=50)
```

--------------------------------

### List Existing API Keys

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/apikeys.md

Retrieve a list of all existing API keys associated with your Gremlin account. This requires the gremlin-python library to be installed and authenticated.

```python
from gremlinapi.apikeys import GremlinAPIapikeys as apikeys
from pprint import pprint
keys = apikeys.list_apikeys()
pprint(keys)
```

--------------------------------

### Manage Gremlin Scenarios Lifecycle

Source: https://context7.com/gremlin/gremlin-python/llms.txt

Control the full lifecycle of Gremlin scenarios, including listing, retrieving, running, fetching run details, halting, archiving, restoring, and updating results. Requires GremlinAPIConfig setup.

```python
from gremlinapi.config import GremlinAPIConfig as config
from gremlinapi.scenarios import (
    GremlinAPIScenarios as Scenarios,
    GremlinAPIScenariosRecommended as RecommendedScenarios,
)

config.bearer_token = "Bearer MU3...ZiTk...Lo...4zO..c="
config.team_id      = "e7352a6b-a9a0-513c-81e4-980f680a70c4"
SCENARIO_GUID       = "ed49ebae-d45d-4412-89eb-aed45d841255"

# List all scenarios
all_scenarios = Scenarios.list_scenarios(teamId=config.team_id)

# Get a single scenario
s = Scenarios.get_scenario(guid=SCENARIO_GUID, teamId=config.team_id)

# Run a scenario
run_result = Scenarios.run_scenario(guid=SCENARIO_GUID, teamId=config.team_id)
run_number = run_result.get("runNumber")

# Fetch run details
run_details = Scenarios.get_scenario_run_details(
    guid=SCENARIO_GUID, runNumber=run_number, teamId=config.team_id
)

# List all runs for a scenario (auto-paginated)
runs = Scenarios.list_scenario_runs(
    guid=SCENARIO_GUID,
    startDate="2024-01-01T00:00:00Z",
    endDate="2024-12-31T23:59:59Z",
    teamId=config.team_id
)

# Halt a running scenario
Scenarios.halt_scenario(
    guid=SCENARIO_GUID, runNumber=run_number, teamId=config.team_id
)

# Archive / restore
Scenarios.archive_scenario(guid=SCENARIO_GUID, teamId=config.team_id)
Scenarios.restore_scenario(guid=SCENARIO_GUID, teamId=config.team_id)

# Annotate a run result
Scenarios.update_scenario_result_flags(
    guid=SCENARIO_GUID,
    runNumber=run_number,
    body={"successFlag": True},
    teamId=config.team_id
)
Scenarios.update_scenario_result_notes(
    guid=SCENARIO_GUID,
    runNumber=run_number,
    body="Service remained healthy throughout the experiment.",
    teamId=config.team_id
)

# Explore Gremlin-curated recommended scenarios
recommended = RecommendedScenarios.list_recommended_scenarios(teamId=config.team_id)
```

--------------------------------

### Create Memory Attack on Hosts

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/attacks.md

Targets 10% of all hosts with a memory attack, consuming 75% of memory per host for one minute. This example uses default targeting for hosts.

```python
from gremlinapi.attacks import GremlinAPIAttacks as attacks
from gremlinapi.attack_helpers import GremlinAttackHelper, GremlinTargetHosts, GremlinMemoryAttack
attacks.create_attack(body=GremlinAttackHelper(target=GremlinTargetHosts(), command=GremlinMemoryAttack()))
```

--------------------------------

### Gremlin Scenario Configuration Example

Source: https://github.com/gremlin/gremlin-python/blob/main/README.md

This JSON structure represents a Gremlin scenario configuration, detailing attacks, targets, and execution steps. It is used to define complex chaos engineering experiments.

```javascript
[
    {
        'create_source': 'WebApp',
        'created_at': '2019-10-14T21:02:47.397Z',
        'created_by': 'community@gremlin.com',
        'description': 'Confidently adopt cloud auto-scaling services. Verify your 
        'users have a positive experience and your application 
        'behaves as expected while hosts come and go.',
        'guid': 'ed49ebae-d45d-4412-89eb-aed45d841255',
        'hypothesis': 'When CPU usage ramps up and hits a set threshold, active 
        'instances will increase and decrease when CPU usage goes 
        'down. User sessions will remain active without throwing any 
        'errors.',
        'last_run_at': '2019-10-14T21:02:47.865Z',
        'name': 'Validate Auto-Scaling',
        'org_id': 'e7352a6b-a9a0-513c-81e4-980f680a70c4',
        'recommended_scenario_id': 'd543fb53-cbd8-4b92-83fb-53cbd8cb9250',
        'state': 'PUBLISHED',
        'steps': [{
                'attacks': [{
                    'attackType': 'ILFI',
                    'impactDefinition': {
                        'commandArgs': {
                            'allCores': True,
                            'cliArgs': ['cpu',
                                '-l',
                                '60',
                                '-p',
                                '5',
                                '-a'
                            ],
                            'length': 60,
                            'percent': 5
                        },
                        'commandType': 'CPU'
                    },
                    'targetDefinition': {
                        'strategy': {
                            'percentage': 100
                        },
                        'strategyType': 'Random',
                        'targetType': 'Container'
                    }
                }],
                'delay': 5
            },
            {
                'attacks': [{
                    'attackType': 'ILFI',
                    'impactDefinition': {
                        'commandArgs': {
                            'allCores': True,
                            'cliArgs': ['cpu',
                                '-l',
                                '60',
                                '-p',
                                '10',
                                '-a'
                            ],
                            'length': 60,
                            'percent': 10
                        },
                        'commandType': 'CPU'
                    },
                    'targetDefinition': {
                        'strategy': {
                            'percentage': 100
                        },
                        'strategyType': 'Random',
                        'targetType': 'Container'
                    }
                }],
                'delay': 5
            },
            {
                'attacks': [{
                    'attackType': 'ILFI',
                    'impactDefinition': {
                        'commandArgs': {
                            'allCores': True,
                            'cliArgs': ['cpu',
                                '-l',
                                '60',
                                '-p',
                                '15',
                                '-a'
                            ],
                            'length': 60,
                            'percent': 15
                        },
                        'commandType': 'CPU'
                    },
                    'targetDefinition': {
                        'strategy': {
                            'percentage': 100
                        },
                        'strategyType': 'Random',
                        'targetType': 'Container'
                    }
                }],
                'delay': 5
            },
            {
                'attacks': [{
                    'attackType': 'ILFI',
                    'impactDefinition': {
                        'commandArgs': {
                            'allCores': True,
                            'cliArgs': ['cpu',
                                '-l',
                                '60',
                                '-p',
                                '20',
                                '-a'
                            ],
                            'length': 60,
                            'percent': 20
                        },
                        'commandType': 'CPU'
                    },
                    'targetDefinition': {

```

--------------------------------

### Manage Attacks with Gremlin Python SDK

Source: https://context7.com/gremlin/gremlin-python/llms.txt

Use the Attacks helper class to list completed attacks filtered by source, halt a specific attack by GUID, or halt all running attacks for a team.

```python
# List all completed attacks filtered to only scenario-sourced
completed = Attacks.list_completed_attacks(
    source="scenario", teamId=config.team_id
)

# Halt a specific attack
Attacks.halt_attack(guid=guid, teamId=config.team_id)

# Halt ALL running attacks for the team
Attacks.halt_all_attacks(teamId=config.team_id)
```

--------------------------------

### Login with User Credentials

Source: https://github.com/gremlin/gremlin-python/blob/main/README.md

Authenticate by providing user email and password. Be cautious as credentials may appear in logs.

```python
import gremlinapi
gremlinapi.login(
    email='user@gremlin.com',
    password='looksL1keIshouldCh4ng3th1sagain!',
    company_name="Gremlin Inc."
)
```

--------------------------------

### Configure GremlinAPI SDK with Proxy Settings

Source: https://context7.com/gremlin/gremlin-python/llms.txt

Configure HTTP and HTTPS proxy settings for SDK communication. Ensure the proxy URL includes user and password if required.

```python
from gremlinapi.config import GremlinAPIConfig as config

config.http_proxy  = "http://user:pass@proxy.corp.example.com:3128"
config.https_proxy = "https://user:pass@proxy.corp.example.com:3128"
```

--------------------------------

### Get Attack Details

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/attacks.md

Retrieves detailed information about a specific attack.

```APIDOC
## Get Attack Details

### Description
Retrieves detailed information about a specific attack.

### Method
`attacks.get_attack`

### Parameters
#### Query Parameters
- **guid** (string) - Required - The unique identifier of the attack.
- **teamId** (string) - Required - The ID of the team.

### Response
#### Success Response (200)
- **attack_details** (object) - An object containing the attack details.

### Request Example
```python
from gremlinapi.attacks import GremlinAPIAttacks as attacks
team_id = 'TEAM_ID/UUID'
attack_id = 'ATTACK_ID'
attack_details = attacks.get_attack(guid=attack_id, teamId=team_id)

from pprint import pprint
pprint(attack_details)
```
```

--------------------------------

### List All Scenarios

Source: https://github.com/gremlin/gremlin-python/blob/main/README.md

This snippet shows the structure for defining and listing scenarios, including target definitions and delays.

```json
{
                    'targetDefinition': {
                        'strategy': {
                            'percentage': 100
                        },
                        'strategyType': 'Random',
                        'targetType': 'Container'
                    }
                }],
                'delay': 5
            }
        ],
        'tiers': ['Free', 'Enterprise'],
        'updated_at': '2019-10-14T20:37:00.314Z'
    },
    ....
]
```

--------------------------------

### Configure GremlinAPI SDK with API Key and Team ID

Source: https://context7.com/gremlin/gremlin-python/llms.txt

Set API key and team ID for authentication. This is the recommended method for automation due to its least-privileged nature.

```python
from gremlinapi.config import GremlinAPIConfig as config

config.api_key = "Key MU3...ZiTk...Lo...4zO..c="
config.team_id = "e7352a6b-a9a0-513c-81e4-980f680a70c4"
```

--------------------------------

### Get Company Details

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/companies.md

Retrieves the details for a specific company using its identifier.

```APIDOC
## Get Company Details

### Description
Retrieves the details for a specific company.

### Method
GET (implied by SDK method)

### Endpoint
/companies/{company_id} (implied by SDK method)

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The unique identifier of the company.

### Request Example
```python
from gremlinapi.companies import GremlinAPICompanies as companies

company_id = 'COMPANY_GUID'
response = companies.get_company(identifier=company_id)
```

### Response
#### Success Response (200)
- **company_details** (object) - Details of the company.
```

--------------------------------

### Create an API Key

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/apikeys.md

Use this Python code to create a new API key. Ensure you have set the necessary environment variables for authentication. The output will provide the key string to set as the GREMLIN_API_KEY environment variable.

```python
import gremlinapi
from gremlinapi.apikeys import GremlinAPIapikeys as apikeys

gremlinapi.login()
key_string = apikeys.create_apikey(identifier='my-first-apikey', description='This is our first API key')
print(f'Set the environment variable GREMLIN_API_KEY to {key_string}')
```

--------------------------------

### Halt Attack

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/halts.md

Halts a specific attack identified by its GUID for a given team.

```APIDOC
## Halt Attack

### Description
Halts a specific attack identified by its GUID for a given team.

### Method
POST

### Endpoint
/v1/attacks/{guid}/halt

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier (GUID) of the attack to halt.
- **teamId** (string) - Required - The ID of the team associated with the attack.
```

--------------------------------

### Deactivate Client

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/clients.md

Deactivates a specific client using its GUID and the team ID.

```APIDOC
## Deactivate Client

### Description
Deactivates a specific client.

### Method
POST (inferred from typical API patterns for deactivation)

### Endpoint
/clients/{guid}/deactivate (inferred)

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier of the client to deactivate.

#### Query Parameters
- **teamId** (string) - Required - The ID of the team the client belongs to.

### Request Example
```python
from gremlinapi.clients import GremlinAPIClients as clients
team_id = 'TEAM_ID'
client_guid = 'CLIENT_GUID'

response = clients.deactivate_client(guid=client_guid, teamId=team_id)
```

### Response
#### Success Response (200)
Details of the deactivated client (schema not provided in source).
```

--------------------------------

### Create API Key

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/apikeys.md

This snippet demonstrates how to create a new API key. It requires authentication, which can be handled via environment variables. The created key string should be set as the GREMLIN_API_KEY environment variable.

```APIDOC
## Create API Key

### Description
Creates a new API key with a specified identifier and description.

### Method
`create_apikey`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **identifier** (string) - Required - A unique name for the API key.
- **description** (string) - Optional - A description for the API key.

### Request Example
```python
import gremlinapi
from gremlinapi.apikeys import GremlinAPIapikeys as apikeys

gremlinapi.login()
key_string = apikeys.create_apikey(identifier='my-first-apikey', description='This is our first API key')
print(f'Set the environment variable GREMLIN_API_KEY to {key_string}')
```

### Response
#### Success Response (200)
- **key_string** (string) - The newly generated API key.

#### Response Example
```
Set the environment variable GREMLIN_API_KEY to <your_api_key_string>
```
```

--------------------------------

### Invite a New User

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/users.md

Send an invitation to a new user via their email address. The user will receive an email to join the team.

```python
from gremlinapi.users import GremlinAPIUsers as users

user_email = 'gizmo@gremlin.com'

confirmation = users.invite_user(email=user_email)
```

--------------------------------

### Get Kubernetes Attack Details

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/kubernetes.md

Retrieves detailed information about a specific Kubernetes attack.

```APIDOC
## Get Kubernetes Attack Details

### Description
Retrieves detailed information about a specific Kubernetes attack.

### Method
GET

### Endpoint
/kubernetes/attacks/{uid}

### Parameters
#### Path Parameters
- **uid** (string) - Required - The unique identifier of the attack.
#### Query Parameters
- **teamId** (string) - Required - The ID of the team to which the attack belongs.
```

--------------------------------

### GremlinTargetHosts / GremlinTargetContainers - Attack Targeting

Source: https://context7.com/gremlin/gremlin-python/llms.txt

Helper classes to select infrastructure for attacks. `GremlinTargetHosts` targets VMs/bare-metal agents, while `GremlinTargetContainers` targets Docker/Kubernetes containers. Both support random and exact selection strategies, and can be narrowed by tags/labels.

```APIDOC
### `GremlinTargetHosts` / `GremlinTargetContainers` — attack targeting

Target helper classes select the infrastructure to attack. `GremlinTargetHosts` matches Gremlin agents on VMs/bare-metal; `GremlinTargetContainers` matches running Docker/Kubernetes containers. Both support `Random` (percentage) and `Exact` (count) selection strategies. Setting `tags`/`labels` narrows the selection; omitting them targets all active hosts/containers.

```python
from gremlinapi.attack_helpers import GremlinTargetHosts, GremlinTargetContainers

# Target 50% of all active hosts
all_hosts_50pct = GremlinTargetHosts(strategy_type="random", percent=50)

```

--------------------------------

### Halt Kubernetes Attack

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/halts.md

Halts a specific Kubernetes attack identified by its GUID for a given team.

```APIDOC
## Halt Kubernetes Attack

### Description
Halts a specific Kubernetes attack identified by its GUID for a given team.

### Method
POST

### Endpoint
/v1/kubernetes/{guid}/halt

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier (GUID) of the Kubernetes attack to halt.
- **teamId** (string) - Required - The ID of the team associated with the attack.
```

--------------------------------

### Set Environment Variables for Authentication

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/apikeys.md

Before creating an API key, set these environment variables for authentication. The GREMLIN_API_KEY will be used by the library after it's created.

```bash
#!/bin/bash
export GREMLIN_USER=my-gremlin-username
export GREMLIN_PASSWORD=my-gremlin-password
export GREMLIN_TEAM_ID=my-gremlin-teamid
```

--------------------------------

### Halt ALFI Experiment

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/halts.md

Halts a specific ALFI experiment using its unique identifier (GUID).

```APIDOC
## Halt ALFI Experiment

### Description
Halts a specific ALFI experiment using its unique identifier (GUID).

### Method
POST

### Endpoint
/v1/alfi/{guid}/halt

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier (GUID) of the ALFI experiment to halt.
```

--------------------------------

### Halt Kubernetes Attack

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/halts.md

Halt a specific Kubernetes attack using its GUID and team ID.

```python
from gremlinapi.kubernetes import GremlinAPIKubernetesAttacks as k8attacks
team_id = 'TEAM_ID/UUID'
attack_id = 'ATTACK_ID'

confirmation = k8attacks.halt_kubernetes_attack(guid=attack_id, teamId=team_id)
```

--------------------------------

### List Scenario Schedules

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/schedules.md

Fetches a list of all scenario schedules. Requires importing the GremlinAPISchedules class.

```python
from gremlinapi.schedules import GremlinAPISchedules as schedules

schedule_list = schedules.list_scenario_schedules()
```

--------------------------------

### Halt Specific Attack

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/halts.md

Halt a particular attack identified by its GUID and associated team ID.

```python
from gremlinapi.attacks import GremlinAPIAttacks as attacks
team_id = 'TEAM_ID/UUID'
attack_id = 'ATTACK_ID'

confirmation = attacks.halt_attack(guid=attack_id, teamId=team_id)
```

--------------------------------

### List Gremlin Scenarios

Source: https://github.com/gremlin/gremlin-python/blob/main/README.md

Use this snippet to list all available scenarios for a given team. Ensure the bearer token and team ID are correctly configured.

```python
from gremlinapi.config import GremlinAPIConfig as config
from gremlinapi.scenarios import GremlinAPIScenarios as scenarios
config.bearer_token = 'Bearer MU3...ZiTk...Lo...4zO..c='
team_id = 'e7352a6b-a9a0-513c-81e4-980f680a70c4'
scenarios_list = scenarios.list_scenarios(teamId=team_id)
```

```python
import pprint
pprint.pprint(scenarios_list)
```

--------------------------------

### Halt ALFI Experiment

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/halts.md

Halt a specific ALFI experiment using its unique identifier (GUID).

```python
from gremlinapi.alfi import GremlinALFI as alfi

alfi_attack_id = 'expirment-guid'
alfi.halt_alfi_experiment(guid=alfi_attack_id)
```

--------------------------------

### Get ALFI Experiment Details

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/alfi.md

Retrieves the details of a specific ALFI experiment using its unique identifier.

```APIDOC
## Get ALFI Experiment Details

### Description
Retrieves the details of a specific ALFI experiment using its unique identifier.

### Method
`alfi.get_alfi_experiment_details(guid: str)`

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier of the ALFI experiment.

### Request Example
```python
from gremlinapi.alfi import GremlinALFI as alfi
from pprint import pprint

alfi_attack_id = 'expirment-guid'
experiment_details = alfi.get_alfi_experiment_details(guid=alfi_attack_id)

pprint(experiment_details)
```

### Response
#### Success Response (200)
- **experiment_details** (dict) - A dictionary containing the details of the ALFI experiment.
```

--------------------------------

### Configure Direct HTTP Proxy

Source: https://github.com/gremlin/gremlin-python/blob/main/README.md

Set direct HTTP and HTTPS proxy configurations for the Gremlin API client. Ensure the proxy URL includes authentication if required.

```python
from gremlinapi.config import GremlinAPIConfig as config
config.http_proxy = 'http://user:pass@myproxy:port'
config.https_proxy = 'https://user:pass@myproxy:port'
```

--------------------------------

### Get Team Details

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/orgs.md

Retrieves detailed information about a specific organization (team) using its ID or UUID.

```APIDOC
## Get Team Details

### Description
Retrieves detailed information about a specific organization (team) using its ID or UUID.

### Method
GET (inferred from get operation)

### Endpoint
/orgs/{identifier} (inferred from context)

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The ID or UUID of the team.

### Response
#### Success Response (200 OK - inferred)
- **team_details** (object) - An object containing the team's details.
```

--------------------------------

### Perform SAML Login with GremlinAPI

Source: https://context7.com/gremlin/gremlin-python/llms.txt

Log in using a SAML assertion and relay state obtained from an Identity Provider (IdP). Returns the bearer token.

```python
import gremlinapi

bearer = gremlinapi.saml_login(
    email="ops@example.com",
    saml_assertion="PHNhbWxwOlJlc3BvbnNl...",
    relay_state="https://app.gremlin.com/"
)
print(bearer)  # 'Bearer eyJhb...'
```

--------------------------------

### Halt Scenario

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/halts.md

Halts a specific scenario run identified by its GUID and run number for a given team.

```APIDOC
## Halt Scenario

### Description
Halts a specific scenario run identified by its GUID and run number for a given team.

### Method
POST

### Endpoint
/v1/scenarios/{guid}/runs/{runNumber}/halt

### Parameters
#### Path Parameters
- **teamId** (string) - Required - The ID of the team associated with the scenario.
- **guid** (string) - Required - The unique identifier (GUID) of the scenario.
- **runNumber** (string) - Required - The run number of the scenario execution to halt.
```

--------------------------------

### Halt Scenario

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/halts.md

Halt a specific scenario run using its team ID, scenario GUID, and run number.

```python
from gremlinapi.scenarios import GremlinAPIScenarios as scenarios
team_id = 'TEAM_ID/UUID'
scenario_id = 'SCENARIO_ID'
scenario_run = 'SCENARIO_RUN_ID'

confirmation = scenarios.halt_scenario(teamId=team_id, guid=scenario_id, runNumber=scenario_run)
```

--------------------------------

### Login with User Credentials and MFA Token

Source: https://github.com/gremlin/gremlin-python/blob/main/README.md

Authenticate using user credentials and a Multi-Factor Authentication token.

```python
import gremlinapi
gremlinapi.login(
    email='user@gremlin.com',
    password='looksL1keIshouldCh4ng3th1sagain!',
    company_name="Gremlin Inc.",
    token="8675309"
)
```

--------------------------------

### Set API Key for Authentication

Source: https://github.com/gremlin/gremlin-python/blob/main/README.md

Configure the SDK to use an API key for authentication. Ensure the key is kept secure.

```python
from gremlinapi.config import GremlinAPIConfig as config
config.api_key = 'Key MU3...ZiTk...Lo...4zO..c='
```

--------------------------------

### Halt a Specific Attack

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/attacks.md

Stops a specific running attack using its GUID and team ID. Requires importing GremlinAPIAttacks.

```python
from gremlinapi.attacks import GremlinAPIAttacks as attacks
team_id = 'TEAM_ID/UUID'
attack_id = 'ATTACK_ID'
confirmation = attacks.halt_attack(guid=attack_id, teamId=team_id)
```

--------------------------------

### GremlinAPIConfig - Global SDK Configuration

Source: https://context7.com/gremlin/gremlin-python/llms.txt

Configure the Gremlin API Python SDK globally by setting credentials, team context, proxy settings, and safety overrides. Values can be read from environment variables or set programmatically.

```APIDOC
## GremlinAPIConfig — global SDK configuration object

Central singleton that stores credentials, team context, proxy settings, and safety overrides. Set properties directly to configure the SDK; values are read from environment variables (`GREMLIN_API_KEY`, `GREMLIN_BEARER_TOKEN`, `GREMLIN_USER`, `GREMLIN_PASSWORD`, `GREMLIN_COMPANY`, `GREMLIN_TEAM_ID`, `GREMLIN_HTTP_PROXY`, `GREMLIN_HTTPS_PROXY`) at import time.

```python
from gremlinapi.config import GremlinAPIConfig as config

# Option 1: API Key authentication (least-privileged, recommended for automation)
config.api_key = "Key MU3...ZiTk...Lo...4zO..c="
config.team_id = "e7352a6b-a9a0-513c-81e4-980f680a70c4"

# Option 2: Bearer Token (higher privilege)
config.bearer_token = "Bearer MU3...ZiTk...Lo...4zO..c="

# Option 3: Proxy support
config.http_proxy  = "http://user:pass@proxy.corp.example.com:3128"
config.https_proxy = "https://user:pass@proxy.corp.example.com:3128"

# Safety overrides for large scenarios
config.override_node_count   = True   # allow >50 nodes per scenario
config.override_blast_radius = True   # allow blast radius >1000 targets

# Check whether a bearer token has expired
if config.is_bearer_expired():
    print("Token expired, re-authenticate")
```
```

--------------------------------

### Deactivate Gremlin Client

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/clients.md

Use this to deactivate a specific Gremlin client. Requires the client's GUID and the team ID.

```python
from gremlinapi.clients import GremlinAPIClients as clients
team_id = 'TEAM_ID'
client_guid = 'CLIENT_GUID'

response = clients.deactivate_client(guid=client_guid, teamId=team_id)
```

--------------------------------

### Create Attack Schedule

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/schedules.md

Creates a new attack schedule with specified command, target, and trigger details. The team ID and a detailed schedule body are required. Ensure the GremlinAPISchedules class is imported.

```python
from gremlinapi.schedules import GremlinAPISchedules as schedules

team_id = 'TEAM ID/UUID'

schedule_body = {
    'command': {
        'type': 'cpu',
        'args': ['-l', '60', '-c', '1']
    },
    'target': {
        'exact': 1,
        'type': 'Random'
    },
    'trigger': {
        'activeDays': ['M', 'T', 'W', 'Th', 'F'],
        'start': '23:00',
        'end': '23:30',
        'timeZone': 'America/New_York',
        'type': 'Random',
        'maxRuns': 1
    }
}

confirmation = schedules.create_attack_schedule(body=schedule_body, teamId=team_id)
```

--------------------------------

### Get Kubernetes Attack Details

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/kubernetes.md

Fetch detailed information about a specific Kubernetes attack. Requires the attack UID and team ID.

```python
from gremlinapi.kubernetes import GremlinAPIKubernetesAttacks as k8attacks
team_id = 'TEAM_ID/UUID'
attack_id = 'ATTACK_UID'

attack_details = k8attacks.get_kubernetes_attack(uid=attack_id, teamId=team_id)
```

--------------------------------

### Invite Company User (Single Email)

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/companies.md

Invite a single user to a company by providing their email address. The email should be in a dictionary format.

```python
from gremlinapi.companies import GremlinAPICompanies as companies

company_id = 'COMPANY_GUID'
user_email_body = { 'email': 'andjohn@gremlin.com' }
response = companies.invite_company_user(identifier=company_id, body=user_email_body)
```

--------------------------------

### Perform Standard Login with GremlinAPI

Source: https://context7.com/gremlin/gremlin-python/llms.txt

Exchange email and password for a bearer token, which is automatically stored in GremlinAPIConfig. Supports optional MFA tokens.

```python
import gremlinapi

gremlinapi.login(
    email="ops@example.com",
    password="S3cur3P@ssw0rd!",
    company_name="Example Corp"
)
```

--------------------------------

### Get Team Details

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/orgs.md

Fetch detailed information about a specific organization (team) by providing its ID or UUID. This requires the team's identifier.

```python
from gremlinapi.orgs import GremlinAPIOrgs as orgs

team_id = 'TEAM ID/UUID'

team_details = orgs.get_org(identifier=team_id)
```

--------------------------------

### Configure GremlinAPI SDK with Bearer Token

Source: https://context7.com/gremlin/gremlin-python/llms.txt

Set a bearer token for authentication. This method provides higher privilege than API key authentication.

```python
from gremlinapi.config import GremlinAPIConfig as config

config.bearer_token = "Bearer MU3...ZiTk...Lo...4zO..c="
```

--------------------------------

### Scenario Graph Construction

Source: https://context7.com/gremlin/gremlin-python/llms.txt

Helper class and node types for building directed graphs representing Gremlin scenarios.

```APIDOC
## GremlinScenarioGraphHelper and Node Classes

### Scenario Graph Construction

Constructs scenarios as directed graphs using `GremlinScenarioGraphHelper` and various node types.

**Node Types:**
- `GremlinScenarioILFINode`: Infrastructure attack node.
- `GremlinScenarioDelayNode`: Wait node.
- `GremlinScenarioStatusCheckNode`: Synchronous health gate node.
- `GremlinScenarioContinuousStatusCheckNode`: Parallel health monitor node.

```python
from gremlinapi.config import GremlinAPIConfig as config
from gremlinapi.scenarios import GremlinAPIScenarios as Scenarios
from gremlinapi.scenario_graph_helpers import (
    GremlinScenarioGraphHelper,
    GremlinScenarioILFINode,
    GremlinScenarioDelayNode,
    GremlinScenarioStatusCheckNode,
)
from gremlinapi.attack_helpers import (
    GremlinCPUAttack,
    GremlinLatencyAttack,
    GremlinTargetHosts,
)

config.api_key = "Key MU3...ZiTk...Lo...4zO..c="
config.team_id = "e7352a6b-a9a0-513c-81e4-980f680a70c4"

# Create the scenario container
scenario = GremlinScenarioGraphHelper(
    name="CPU Ramp Test",
    description="Gradually increase CPU load and verify auto-scaling",
    hypothesis="Service remains healthy as CPU scales up; instances scale out"
)

# Create nodes
cpu_low = GremlinScenarioILFINode(
    command=GremlinCPUAttack(length=60, capacity=30, all_cores=True),
    target=GremlinTargetHosts(strategy_type="random", percent=50)
)
delay1 = GremlinScenarioDelayNode(delay=10)
health_check = GremlinScenarioStatusCheckNode(
    description="Verify service responds",
    endpoint_url="https://service.internal/health",
    endpoint_headers={"Authorization": "Bearer healthtoken"},
    evaluation_ok_status_codes=["200"],
    evaluation_ok_latency_max=300
)
cpu_high = GremlinScenarioILFINode(
    command=GremlinCPUAttack(length=60, capacity=80, all_cores=True),
    target=GremlinTargetHosts(strategy_type="random", percent=50)
)

# Add nodes and connect them to form the graph
scenario.add_node(cpu_low)
scenario.add_node(delay1)
scenario.add_node(health_check)
scenario.add_node(cpu_high)

scenario.add_edge(delay1, cpu_low)
scenario.add_edge(health_check, delay1)
scenario.add_edge(cpu_high, health_check)

# Submit the scenario to the Gremlin API
result = Scenarios.create_scenario(body=scenario, teamId=config.team_id)
print(f"Created scenario: {result['guid']}")
```
```

--------------------------------

### Create Latency Attack (Helper)

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/attacks.md

Launches a latency attack using helper classes for a more Pythonic approach. Requires importing GremlinAPIAttacks, GremlinAttackHelper, GremlinTargetContainers, and GremlinLatencyAttack.

```python
from gremlinapi.attacks import GremlinAPIAttacks as attacks
from gremlinapi.attack_helpers import GremlinAttackHelper, GremlinTargetContainers, GremlinLatencyAttack

attacks.create_attack(
    body=GremlinAttackHelper(
        target=GremlinTargetContainers(strategy_type='Random', target_all_hosts=True,
            percent=100, labels={'com.amazonaws.ecs.container-start': 'swissknife'}),
        command=GremlinLatencyAttack(length=300, protocol='ICMP', delay=100)))
```

--------------------------------

### Invite Company User (Multiple Emails)

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/companies.md

Invite multiple users to a company by providing a list of email objects. Each object can specify emails in different formats.

```python
from gremlinapi.companies import GremlinAPICompanies as companies

company_id = 'COMPANY_GUID'
user_email_body = [{ 'emails': 'andjohn+1@gremlin.com'}, { 'email': 'andjohn+2@gremlin.com'}]
response = companies.invite_company_user(identifier=company_id, body=user_email_body)
```

--------------------------------

### Gremlin API Attacks - Create and Manage

Source: https://context7.com/gremlin/gremlin-python/llms.txt

Configure API credentials and use the GremlinAPIAttacks class to create, retrieve, and list attacks. Attacks can be built using helper classes or raw dictionaries.

```python
from gremlinapi.config import GremlinAPIConfig as config
from gremlinapi.attacks import GremlinAPIAttacks as Attacks
from gremlinapi.attack_helpers import (
    GremlinAttackHelper,
    GremlinLatencyAttack,
    GremlinTargetContainers,
)

config.api_key = "Key MU3...ZiTk...Lo...4zO..c="
config.team_id = "e7352a6b-a9a0-513c-81e4-980f680a70c4"

# Build attack with helpers
attack = GremlinAttackHelper(
    command=GremlinLatencyAttack(length=60, delay=150),
    target=GremlinTargetContainers(
        strategy_type="random",
        percent=10,
        target_all_containers=False,
        labels={"service": "checkout"}
    )
)

# Create (launch) the attack — returns attack GUID
guid = Attacks.create_attack(body=attack, teamId=config.team_id)
print(f"Launched attack: {guid}")

# Fetch details of a running or completed attack
details = Attacks.get_attack(guid=guid, teamId=config.team_id)

# List all currently active attacks (auto-paginates)
active = Attacks.list_active_attacks(teamId=config.team_id)
```

--------------------------------

### Create Latency Attack (Helper)

Source: https://github.com/gremlin/gremlin-python/blob/main/examples/attacks.md

Launches a latency attack using helper classes for easier configuration.

```APIDOC
## Create Latency Attack (Helper)

### Description
This will also launch a 100ms latency attack, limited to ICMP traffic, against a single random container with the ECS container-name `swissknife`, using the built in helper vs. providing your own json.

### Method
`attacks.create_attack`

### Parameters
#### Request Body
- **target** (GremlinTargetContainers) - Required - Specifies the target containers for the attack.
  - **strategy_type** (string) - Required - Strategy type, e.g., 'Random'.
  - **target_all_hosts** (bool) - Required - Whether to target all hosts.
  - **percent** (int) - Required - Percentage of targets.
  - **labels** (dict) - Required - Labels to filter containers.
    - **com.amazonaws.ecs.container-start** (string) - Required - Container start label.
- **command** (GremlinLatencyAttack) - Required - Defines the latency attack parameters.
  - **length** (int) - Required - Latency length.
  - **protocol** (string) - Required - Protocol, e.g., 'ICMP'.
  - **delay** (int) - Required - Delay in milliseconds.

### Request Example
```python
from gremlinapi.attacks import GremlinAPIAttacks as attacks
from gremlinapi.attack_helpers import GremlinAttackHelper, GremlinTargetContainers, GremlinLatencyAttack

attacks.create_attack(
    body=GremlinAttackHelper(
        target=GremlinTargetContainers(strategy_type='Random', target_all_hosts=True,
            percent=100, labels={'com.amazonaws.ecs.container-start': 'swissknife'}),
        command=GremlinLatencyAttack(length=300, protocol='ICMP', delay=100)))
```
```