Skip to content

Latest commit

 

History

History
179 lines (117 loc) · 7.62 KB

README.md

File metadata and controls

179 lines (117 loc) · 7.62 KB
Raw

NGWAF CLI Tool

A comprehensive Python toolset for managing NG WAF deployments on Fastly services, including provisioning, edge security object management, traffic ramping, backend synchronization, VCL upgrades, configuration updates, and Salt dashboard integration.

Prerequisites

Before running any of the scripts, ensure the following are installed and set up:

  • Python 3.x
  • Requests library for Python (pip3 install requests)
  • Parsel library (pip3 install parsel)
  • Fastly API token and NGWAF token
  • Cookie files: .voltron_cookie for Voltron access and .dashboard_cookie for Salt Dashboard access.

How to Obtain the Cookie Values

.voltron_cookie File

To access Voltron for group management and certain NG WAF API calls, you need a .voltron_cookie file with the full cookie value. Here’s how to set it up:

  1. Login to Voltron Dashboard: Open your browser, navigate to Voltron, and log in.
  2. Open Developer Tools: Right-click on the page, select "Inspect" (or press F12), and go to the Network tab.
  3. Capture a cURL Request: Perform any action on the Voltron dashboard to trigger a request. Locate a Voltron request, right-click, and select "Copy as cURL."
  4. Extract the Cookie: From the copied cURL, find the -H 'cookie: ...' section, and copy the entire cookie string.
  5. Create a .voltron_cookie File: In your project directory, create a .voltron_cookie file that includes the cookie string.

Example .voltron_cookie content:

_ga=GA1.2.184163117.1724087216; _gid=GA1.2.1553403690.1725903286; goth-session=MTcyNTk...

.dashboard_cookie File

Similarly, for accessing the Salt dashboard, you need a .dashboard_cookie file. Follow these steps:

  1. Login to Salt Dashboard: Open your browser, navigate to the Salt dashboard, and log in.
  2. Open Developer Tools: Right-click on the page, select "Inspect" (or press F12), and go to the Network tab.
  3. Capture a cURL Request: Perform any action on the Salt dashboard to trigger a request. Locate a Salt dashboard request, right-click, and select "Copy as cURL."
  4. Extract the Cookie: From the copied cURL, find the -H 'cookie: ...' section, and copy the entire cookie string.
  5. Create a .dashboard_cookie File: In your project directory, create a .dashboard_cookie file that includes the cookie string.

Example .dashboard_cookie content:

_ga=GA1.2.184163117.1724087216; _gid=GA1.2.1553403690.1725903286; session-token=xyz...

Cookie Expiration Check

Both .voltron_cookie and .dashboard_cookie files are checked for expiration. If either file is older than one day, the user will be prompted to re-enter the cookie value to ensure up-to-date access.

Environment Variable Setup

The setup-env.zsh script helps streamline setting up environment variables required by the scripts. Environment variables allow you to omit certain command-line arguments.

Running the setup-env.zsh Script

  1. Make the script executable:

    chmod +x setup-env.zsh

  2. Run the script:

    source setup-env.zsh --update-file
    • The script will prompt you to enter values for CORP_NAME, NGWAF_TOKEN, and FASTLY_TOKEN.
    • If the --update-file flag is passed, it will also prompt for site_name and service_id and update file.csv.

  3. Reload the terminal environment: After running the script, reload your .zshrc:

    source ~/.zshrc

Using the Environment Variables

Once the environment variables are set, you can load them in future sessions using a custom function generated by the script:

setenv_<CORP_NAME>

Replace <CORP_NAME> with the actual name you provided during the setup.

List of Environment Variables

  • NGWAF_USER_EMAIL: Your NG WAF user email
  • NGWAF_TOKEN: NG WAF API token
  • FASTLY_TOKEN: Fastly API token
  • CORP_NAME: Your corporation name
  • SITE_NAME: (Optional) Site name for individual operations
  • FASTLY_SID: (Optional) Fastly Service ID for individual operations

These variables enable you to execute scripts without specifying all parameters on the command line.

Scripts Overview and Usage

The ngwafcli toolset includes several scripts for managing NG WAF services on Fastly. Each script can be executed using command-line arguments for various functions, as described below.

1. Main NGWAF CLI (ngwafcli.py)

This script handles core operations, including provisioning, edge security object management, adding corp groups, and backend synchronization.

Usage

python3 ngwafcli.py --csv_file file.csv --activate true --percent_enabled 100 --provision --dynamic-backend --premier

Key Features and Flags

  • Provisioning: Use --provision to create and map sites in Fastly.
  • Edge Security Management: Automatically creates an edge security object if not present.
  • Traffic Control: Use --percent_enabled to control traffic routed to NG WAF.
  • Backend Synchronization: Use --sync-backend with a CSV file to synchronize origins.
  • Dynamic Backend and Premier Groups: Use --dynamic-backend to add to sigsci-edge-dynamic-backends and --premier to add to the rate-limiting group.
  • Retry Mechanism: Automatically retries API calls on network failures.

2. VCL Version Updater (upgrade-vcl-version.py)

The upgrade-vcl-version.py script updates the VCL version for NG WAF to the latest release. This ensures that your service benefits from the latest security and performance enhancements available for VCL.

Usage

python3 upgrade-vcl-version.py --ngwaf_user_email 'your_ngwaf_user_email' --ngwaf_token 'your_ngwaf_token' --fastly_token 'your_fastly_token' --corp_name 'your_corp_name'

3. Configuration Updater (config-updater.py)

The config-updater.py script takes a .json configuration file and applies it across multiple sites listed in file.csv. This script is also useful for updating webhook site integrations and other configuration variables for each site.

Usage

python3 config-updater.py --config_file 'path/to/config.json' --csv_file 'path/to/file.csv' --ngwaf_user_email 'your_ngwaf_user_email' --ngwaf_token 'your_ngwaf_token' --fastly_token 'your_fastly_token' --corp_name 'your_corp_name'

Configuration Details

  • Config File: The JSON file should define any settings to be updated across sites, such as webhook URLs or integration variables.
  • CSV File: The CSV file should contain site_name and fastly_sid for each site to be updated.

4. voltron.py for Corp Group Management

The voltron.py script manages adding corps to specific groups in NG WAF, such as sigsci-edge-dynamic-backends or rate-limiting. It uses the .voltron_cookie file for authentication.

Usage

python3 voltron.py --corp 'your_corp_name' --action 'add' --groups 'sigsci-edge-dynamic-backends' 'rate-limiting'

CSV Input for Batch Processing

All major scripts support batch processing using a CSV file containing site_name and fastly_sid columns.

Example CSV format:

site_name,fastly_sid
site1,serviceID1
site2,serviceID2

Use this format when specifying --csv_file.

Video Tutorials

For additional guidance, please refer to the following walkthroughs:

Contact

Sina Siar - @ssiar - [email protected]