Skip to main content

Script Directories

Each agent resource has a script directory configured in the EntryGuard dashboard. The directory contains apply/ and revoke/ subdirectories with numbered scripts that the agent discovers and executes in order.

Directory Structure​

/etc/eg-agent/scripts/my-resource/
├── apply/
│   ├── 01-ufw.sh
│   ├── 02-traefik.sh
│   └── 03-nginx-reload.sh
└── revoke/
    ├── 01-ufw.sh
    ├── 02-traefik.sh
    └── 03-nginx-reload.sh

How It Works​

When a session starts:

  1. EntryGuard sends an APPLY command with the script directory path
  2. The agent looks in <scriptDir>/apply/ for scripts matching the NN- naming convention
  3. Scripts execute in order: 01-ufw.sh, then 02-traefik.sh, then 03-nginx-reload.sh
  4. All scripts run regardless of individual failures — if 01-ufw.sh fails, 02-traefik.sh still runs
  5. Per-script results (success/failure, output, duration) are reported back to EntryGuard

The same flow applies for REVOKE commands using the <scriptDir>/revoke/ subdirectory.

Setup​

1. Create the Script Directory​

# Create the directory structure for a resource
sudo mkdir -p /etc/eg-agent/scripts/my-resource/{apply,revoke}

Each resource gets its own directory. A single agent can serve multiple resources with different script directories.

2. Write Your Scripts​

Every script receives two arguments:

  • $1 (bash) / $args[0] (PowerShell) — The CIDR to apply or revoke (e.g., 203.0.113.50/32)
  • $2 (bash) / $args[1] (PowerShell) — A description string (e.g., EntryGuard session abc-123)

Exit code 0 means success. Any other exit code means failure. All stdout/stderr output is captured and reported back to EntryGuard.

The naming convention is required: scripts must start with a numeric prefix followed by a hyphen (NN-). Files without this prefix are ignored.

/etc/eg-agent/scripts/my-resource/apply/01-ufw.sh
#!/bin/bash
set -euo pipefail
CIDR="$1"
ufw allow from "$CIDR" to any port 22 comment "entryguard"
echo "Allowed $CIDR on port 22 (UFW)"
/etc/eg-agent/scripts/my-resource/revoke/01-ufw.sh
#!/bin/bash
set -euo pipefail
CIDR="$1"
ufw delete allow from "$CIDR" to any port 22 || true
echo "Revoked $CIDR on port 22 (UFW)"
Make scripts executable
chmod +x /etc/eg-agent/scripts/my-resource/apply/*.sh
chmod +x /etc/eg-agent/scripts/my-resource/revoke/*.sh

3. Configure the Resource in EntryGuard​

In the dashboard:

  1. Go to Resources
  2. Create or edit an AGENT resource (type: Script)
  3. Set the Script Directory field to the path on the agent host (e.g., /etc/eg-agent/scripts/my-resource)
  4. Optionally set Script Timeout (seconds per script, default: 30)

4. Test​

Start a session and check the expanded session details in the dashboard. You'll see per-script status for each script that ran:

✓ 01-ufw.sh          (45ms)
✗ 02-traefik.sh       (120ms)  Traefik config file not found
✓ 03-nginx-reload.sh  (30ms)

Naming Convention​

Scripts must start with a numeric prefix followed by a hyphen:

ValidInvalid
01-ufw.shufw.sh
02-traefik.shtraefik-apply.sh
10-cleanup.shcleanup.sh
99-notify.ps1notify.ps1

Files without the NN- prefix are silently skipped. This lets you keep README files, helper libraries, or disabled scripts in the same directory without them being executed.

Scripts are sorted lexicographically by filename, so 02- runs before 10-, and 10- runs before 99-.

Execution Behavior​

All Scripts Run Regardless of Failures​

Both apply and revoke execute all discovered scripts even if earlier ones fail. This prevents partial states — if your UFW script fails but your Traefik script succeeds, you know exactly which layer needs attention.

Per-Script Timeout​

Each script gets its own timeout (configured via the Script Timeout field on the resource, default 30 seconds). If a script exceeds the timeout, it's killed and reported as failed. The next script still runs.

Per-Script Results​

The dashboard shows individual results for each script:

  • Script name
  • Success or failure status
  • Execution time
  • Error output (if failed)

This makes it easy to identify exactly which script in a chain caused an issue.

One Resource, One Script Directory​

Each resource points to one script directory. If you have multiple servers or different configurations, create separate resources:

/etc/eg-agent/scripts/
├── bastion/                  ← Resource "bastion-host"
│   ├── apply/
│   │   ├── 01-ufw-ssh.sh
│   │   └── 02-ufw-http.sh
│   └── revoke/
│       ├── 01-ufw-ssh.sh
│       └── 02-ufw-http.sh
├── webserver/                ← Resource "web-01"
│   ├── apply/
│   │   ├── 01-nginx.sh
│   │   └── 02-traefik.sh
│   └── revoke/
│       ├── 01-nginx.sh
│       └── 02-traefik.sh
└── simple/                   ← Resource "dev-box"
    ├── apply/
    │   └── 01-ufw.sh
    └── revoke/
        └── 01-ufw.sh

Even for a single script, use the directory structure — put one file in apply/ and one in revoke/.

Windows Support​

Script directories work on Windows too. Use PowerShell scripts with the same naming convention:

C:\eg-agent\scripts\bastion\
├── apply\
│   ├── 01-firewall.ps1
│   └── 02-iis-restriction.ps1
└── revoke\
    ├── 01-firewall.ps1
    └── 02-iis-restriction.ps1

Next Steps​