Smarter by Design.Simpler for Business
ags security
ags security is the command group that collects the policies that protect the access flow against abuse. It does not have its own action; it consists of four subcommands.
| Subcommand | What it manages | The panel screen |
|---|---|---|
ags security lockout-policies | The locking of the account after the failed attempts | Account Lockout Policies |
ags security session-protection-policies | The binding of the session, its periods and the concurrent session limit | Session Protection Policies |
ags security rate-limit-policies | The bot protection policies: the trigger and the action to be applied | Bot Protection Policies |
ags security captcha-providers | The CAPTCHA provider definitions | Captcha Providers |
The command name does not overlap with the screen name
The rate-limit-policies command manages the records that are named Bot Protection Policies in the panel. The rate limiting is one trigger type of these policies.
The policies come into service by being bound to the gateway; the CAPTCHA providers, on the other hand, are bound not directly to the gateway but to the lockout and bot protection policies that use it.
admin@TR7LBWAF01> ags gateway update id <vService> \
--defaultLockoutPolicies.0 <lockout> --sessionProtectionPolicy <session> --botProtectionPolicies.0 <bot>
admin@TR7LBWAF01>
Command Summary
# Tab after the command
admin@TR7LBWAF01> ags security
captcha-providers lockout-policies rate-limit-policies
session-protection-policies
admin@TR7LBWAF01> ags security lockout-policies
add delete list show update
admin@TR7LBWAF01> ags security lockout-policies list
admin@TR7LBWAF01> ags security lockout-policies show <id>
admin@TR7LBWAF01> ags security lockout-policies add name <name> …
admin@TR7LBWAF01> ags security lockout-policies update id <id> …
admin@TR7LBWAF01> ags security lockout-policies delete <id>
admin@TR7LBWAF01> ags security session-protection-policies list
admin@TR7LBWAF01> ags security session-protection-policies show <id>
admin@TR7LBWAF01> ags security session-protection-policies add name <name> …
admin@TR7LBWAF01> ags security session-protection-policies update id <id> …
admin@TR7LBWAF01> ags security session-protection-policies delete <id>
admin@TR7LBWAF01> ags security rate-limit-policies list
admin@TR7LBWAF01> ags security rate-limit-policies show <id>
admin@TR7LBWAF01> ags security rate-limit-policies add name <name> …
admin@TR7LBWAF01> ags security rate-limit-policies update id <id> …
admin@TR7LBWAF01> ags security rate-limit-policies delete <id>
admin@TR7LBWAF01> ags security captcha-providers list
admin@TR7LBWAF01> ags security captcha-providers show <id>
admin@TR7LBWAF01> ags security captcha-providers add name <name> …
admin@TR7LBWAF01> ags security captcha-providers update id <id> …
admin@TR7LBWAF01> ags security captcha-providers delete <id>
admin@TR7LBWAF01>
In each of the four subcommands there are five actions. In the show and delete commands the identifier is written without a field name, and in the update command it is in the id <id> form.
ags security lockout-policies
It locks the access after a certain number of failed attempts. The lockout scope, the thresholds and the periods are determined here.
| Order | Field | Status | Value |
|---|---|---|---|
| 1 | name | Required | The name of the policy |
| 2 | scope | Required | What will be counted: username · username_ip · ip · composite |
| 3 | captchaProviderId | Conditionally required | It is asked for as long as the CAPTCHA protection is on; --captchaProtection false is written in order to turn it off |
| 4 | lockoutAttemptThreshold | Required | After how many failed attempts it will be locked |
| 5 | lockoutDuration.val · lockoutDuration.unit | Required | The lockout period and its unit |
| Optional setting | Default | Value |
|---|---|---|
--captchaProtection | true | It shows a CAPTCHA before the lockout |
--captchaAttemptThreshold | 4 | After how many attempts the CAPTCHA will be shown |
--warningAttemptThreshold | 3 | After how many attempts the warning will be shown |
--escalateRepeatedLockouts | true | It doubles the period in the repeated lockouts |
--maxLockoutDuration.val · --maxLockoutDuration.unit | 24 hours | The upper limit of the doubled period |
--attemptWindowDuration.val · --attemptWindowDuration.unit | 24 hours | The time window in which the attempts are counted |
--components.0 | — | According to which components the counting will be made in the composite scope |
--policyCondition | Without a condition | It makes the policy be applied only in certain requests |
# the CAPTCHA is off: a provider is not asked for
admin@TR7LBWAF01> ags security lockout-policies add name user-lockout \
scope username lockoutAttemptThreshold 5 lockoutDuration.val 15 lockoutDuration.unit m \
--captchaProtection false
admin@TR7LBWAF01>
ags security session-protection-policies
It determines to which information the session will be bound, for how long it will be valid and the concurrent session limit.
| Order | Field | Status | Value |
|---|---|---|---|
| 1 | name | Required | The name of the policy |
| 2 | sessionBindingType | Required | To what the session will be bound: none · ip · ip+ua · composite |
| 3 | concurrentSessionAction | Required | When the concurrent session limit is exceeded: deny · logout_oldest · logout_all |
| Optional setting | Default | Value |
|---|---|---|
--maxConcurrentSessions | — | The number of sessions that can stay open at the same time |
--sessionIdleTimeout.val · --sessionIdleTimeout.unit | 8 hours | The inactivity period |
--sessionAbsoluteTimeout.val · --sessionAbsoluteTimeout.unit | 7 days | The longest life of the session |
--sessionBindingComponents.0 | — | The components to be used in the composite binding |
--whitelistCond | — | The requests to be kept exempt from the binding check |
admin@TR7LBWAF01> ags security session-protection-policies add name strict-session sessionBindingType ip+ua \
--maxConcurrentSessions 2 --concurrentSessionAction logout_oldest \
--sessionIdleTimeout.val 30 --sessionIdleTimeout.unit m
admin@TR7LBWAF01>
ags security rate-limit-policies
It consists of a trigger and an action: in which case it will come into service and what it will do when it comes into service.
| Order | Field | Status | Value |
|---|---|---|---|
| 1 | name | Required | The name of the policy |
| 2 | triggerType | Required | static · requests · failedAuthAttempts · botScore |
| 3 | requestsThreshold | Conditionally required | Only triggerType requests; the request threshold per window |
| 3 | failedAuthThreshold | Conditionally required | Only triggerType failedAuthAttempts; the failed login threshold per window |
| 3 | botScoreThreshold | Conditionally required | Only triggerType botScore; the bot score threshold |
| 4 | scope | Conditionally required | In the triggers other than static: global · ip · ip+ua · composite |
| 5 · 6 | triggerTrackingWindow.val · triggerTrackingWindow.unit | Conditionally required | The window in which the events are counted; it is not asked for in the static and botScore triggers |
| 6 | action | Required | deny · tarpit · block · bwLimit · captcha · showContent |
| The setting specific to the action | Default | In which action |
|---|---|---|
--denyStatus | 429 | deny and tarpit |
--blockStatusCode | 403 | block |
--uploadLimit · --downloadLimit | — | bwLimit; kilobits/second |
captchaProviderId | — | captcha; Conditionally required |
--contentProfile · --contentStatusCode | 403 | showContent |
--blockDuration.val · --blockDuration.unit | 5 minutes | The period for which the action lasts |
--policyCondition · --components.0 | — | The condition and the composite scope components |
The botScore trigger
botScore uses the Threat Protection bot score of the vService. For this to work, the bot protection must be on in the vService; the monitoring mode is enough as well.
# block the IP that exceeds 100 requests per minute for 5 minutes
admin@TR7LBWAF01> ags security rate-limit-policies add name request-limit triggerType requests \
requestsThreshold 100 scope ip triggerTrackingWindow.val 1 triggerTrackingWindow.unit m action block
# ask for a CAPTCHA in the failed logins
admin@TR7LBWAF01> ags security rate-limit-policies add name login-captcha triggerType failedAuthAttempts \
failedAuthThreshold 5 scope ip triggerTrackingWindow.val 10 triggerTrackingWindow.unit m \
action captcha captchaProviderId <captcha>
admin@TR7LBWAF01>
ags security captcha-providers
It defines with which service the CAPTCHA verification will be made. After the provider is selected, only the fields of that provider are asked for.
| Order | Field | Status | Value |
|---|---|---|---|
| 1 | name | Required | The name of the provider record |
| 2 | provider | Required | tr7 · recaptcha · hcaptcha · turnstile |
| 3–5 | tr7CaptchaType · tr7CaptchaDifficulty · tr7MaxAttempts | Conditionally required | Only provider tr7 |
| 6 · 7 | challengeTTL.val · challengeTTL.unit | Conditionally required | Only provider tr7; the period given for the question to be answered. Even if there is -- on the line, it is written without a prefix |
| 3–5 | recaptchaSiteKey · recaptchaSecretKey · recaptchaVersion | Conditionally required | Only provider recaptcha |
| 3–5 | hcaptchaSiteKey · hcaptchaSecretKey · hcaptchaDifficulty | Conditionally required | Only provider hcaptcha |
| 3–5 | turnstileSiteKey · turnstileSecretKey · turnstileMode | Conditionally required | Only provider turnstile |
The fields specific to the provider are written without a prefix if there is no field that begins with -- on the line, and with the -- prefix if there is.
provider | Its required fields |
|---|---|
tr7 | tr7CaptchaType (text · math) · tr7CaptchaDifficulty · tr7MaxAttempts |
recaptcha | recaptchaSiteKey · recaptchaSecretKey · recaptchaVersion (v2_checkbox · v2_invisible · v3); if v3 is selected, recaptchaV3Threshold additionally |
hcaptcha | hcaptchaSiteKey · hcaptchaSecretKey · hcaptchaDifficulty (easy · moderate · difficult · always_on) |
turnstile | turnstileSiteKey · turnstileSecretKey · turnstileMode (managed · non-interactive · invisible) |
| Optional setting | Default | Value |
|---|---|---|
--validFor.val · --validFor.unit | 5 minutes | The validity period of a successful verification |
--namespace | The default route table of the device | The route table from which the external provider will be gone out to; in the providers other than tr7 |
# the CAPTCHA that works on the device
admin@TR7LBWAF01> ags security captcha-providers add name local-captcha provider tr7 \
tr7CaptchaType text tr7CaptchaDifficulty 3 tr7MaxAttempts 3 challengeTTL.val 2 challengeTTL.unit m
# an external service
admin@TR7LBWAF01> ags security captcha-providers add name turnstile-captcha provider turnstile \
turnstileSiteKey <site-key> turnstileSecretKey <secret-key> turnstileMode managed
admin@TR7LBWAF01>
Things to Know
- The period fields are in two parts. In every period
--field.valtakes the value and--field.unittakes the unit. - The CAPTCHA provider is created first. A lockout policy while the CAPTCHA protection is on, and a bot protection policy in the
captchaaction, ask for a provider record. - The policies do not work without being bound to the gateway. The lockout and bot protection policies are bound with list fields, and the session protection policy with a single selection.
- The keys of the external provider are written on the command line. The site and secret keys are not asked for secretly; they appear on the line and fall into the command history.
- The lockout behavior can be changed on a step basis. The
--lockoutBehaviourfield in the provider and MFA commands makes different policies be applied in that step.
