> For the complete documentation index, see [llms.txt](https://paracyberbellum.gitbook.io/pyrasp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://paracyberbellum.gitbook.io/pyrasp/5.-cloud-operations.md).

# 5. Cloud Operations

`pyrasp` is capable to operate in a 'cloud' environment:

* Retrieve initial configuration and updates from remote server
* Retrieve Blacklist from remote server at startup
* Provide regular agent status to remote server
* Provide basic telemetry (cpu & memory usage, number of requests)
* Share new blacklisted entries
* Update blacklist with new entries provided by remote server

## Run

### Flask & FastAPI

`pyrasp` instance creation requires 2 specific arguments:

* `cloud_url`: URL to retrieve agent configuration from
* `key`: unique key to identify the agent

`<rasp_class>(<framework_instance>, cloud_url = <configuration_url>, key = <agent_key>)`

> Those 2 parameters can be set as environment vaiables - see [Environment Variables](#environment-variables)

```python
from pyrasp.pyrasp import FastApiRASP
app = FastAPI()
rasp = FastApiRASP(app, cloud_url = 'https://pyrasp.my.org/config', key = '000000-1111-2222-3333-44444444' )
```

### Django

For cloud agents, `PYRASP_CLOUD_URL` and `PYRASP_KEY` variables must be added to the `settings.py` file of the Django application:

* `PYRASP_CLOUD_URL` contains the URL to retrieve agent configuration from
* `PYRASP_KEY` is used by the server to uniquely identify the agent.

```python
PYRASP_CLOUD_URL = 'https://pyrasp.my.org/config'
PYRASP_KEY = '000000-1111-2222-3333-44444444'

MIDDLEWARE = [
    'pyrasp.pyrasp.DjangoRASP',
    ...
]
```

### AWS Lambda, Google Cloud Functions and Azure Function

`pyrasp` instance creation requires 2 specific arguments:

* `cloud_url`: URL to retrieve agent configuration from
* `key`: unique key to identify the agent

`@<rasp_class>(cloud_url = <configuration_url>, key = <agent_key>)`

> Those 2 parameters can be set as environment variables - see [Environment Variables](#environment-variables)

```python
@LambdaRASP(cloud_url = 'https://pyrasp.my.org/config', key = '000000-1111-2222-3333-44444444').register
def lambda_handler(event, context):
...
```

```python
@GcpRASP(cloud_url = 'https://pyrasp.my.org/config', key = '000000-1111-2222-3333-44444444').register
def lambda_handler(event, context):
...
```

### Environment Variables

`cloud_url` and `key` values can be set as environment variables:

* `PYRASP_CLOUD_URL`: URL to retrieve agent configuration from
* `PYRASP_KEY`: unique key to identify the agent

## Connection

Upon connection the `pyrasp` agent sends a POST request to the specified `PYRASP_CLOUD_URL`. Format of the JSON content is provided below.

```json
{
    "key": "<PYRASP_KEY>",
    "version": "<PYRASP_VERSION>",
    "platform": "<RUNNING_PLATFORM>",
    "routes": {
        "<endpoint>": {
            "methods": [ "<http_alowed_method>", ... ],
            "path": "<path>"
        }
    }
}
```

## Configuration download

### Overview

Configuration file and blacklist are retrieved by the agent through a `GET` request to the URL specified.

At agent startup the remote configuration URL is displayed.

```
### PyRASP v0.9.2 ##########
[+] Starting PyRASP
[+] Loading template configuration: default
[+] Loading configuration from http://pyrasp.my.org/config
[+] XSS model loaded
[+] SQLI model loaded
[+] Prompt Injection model loaded
[+] Starting logging process
[+] PyRASP succesfully started
############################
```

### Format

The response to the request **MUST** be an `application/json` body containing the configuration.\
The data structure **MUST** be a dictionary (`{}`)

The JSON configuration **MUST** be provided in the `config` key.\
Optionaly an initial blacklist can be provided as a dictionary structure in the `blacklist` key of the response.\
The blacklist structure **MUST** comply with the format detailed in the example below.

### Configuration example

```json
{
    "config": {
        "HOSTS" : ["mysite.mydomain.com"],
        "APP_NAME" : "Web Server",
        "GTFO_MSG" : "<html><head /><body><h1>You have been blocked</h1></body></html>",
        "DENY_STATUS_CODE": 403,
        ...
    },
    "blacklist": {
        "<ip_address>": <detection_epoch_time>,
        ...
    }
}
```