Doc improvements

docs/src/appendix/security.md

@@ -0,0 +1,52 @@
+# Security
+
+`attempt` is primarily intended to be run in local development environments, where the attack
+surface is limited or nonexistant. If you are running `attempt` in a production/untrusted
+environment, you should be aware of the potential for vulnerabilities.
+
+# Classes of vulnerability
+
+`attempt` is vulnerable to three primary classes of vulnerability:
+
+- Terminating retries before an application has succeeded
+- Retrying an application that has already succeed
+- Denial of service attacks
+
+# Potential vulnerabilities
+
+## Manipulating output predicates
+
+If your application logs includes in it's output data from remote hosts or other untrusted sources,
+it is likely that attackers will be able to manipulate output predicates. Attackers will likely be
+able to trigger retry or stop predicates in inappropriate situations.
+
+## Denial of service attacks on output predicates
+
+Attackers able to influence the output of your application may mount denial of service attacks by
+causing it to include invalid UTF-8, which crashes `attempt`. They may also be able to crash
+`attempt` by making the output large.
+
+If you are using regex predicates, attackers may be able to mount denial of service attacks by
+supplying
+[pathological inputs](https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS).
+
+## Sending signals to child processes
+
+An attacker with access to the system `attempt` is running on could manipulate signal predicates by
+sending signals to `attempt`'s child process.
+
+# Mitigations
+
+## Write child processes to be idempotent
+
+Whenever possible, child processes should be written such that they tolerate being retried on a
+success.
+
+## Avoid output predicates
+
+Prefer the use of status predicates to output predicates. Status predicates are more difficult to
+manipulate.
+
+## Setup alerting for failed processing
+
+If you are relying on your application to run,

docs/src/backoff/exponential.md

@@ -4,18 +4,19 @@ Wait exponentially more time between attempts, using the following formula:
 
 `<multiplier> * (<base> ^ <attempts>)`
 
+The attempt counter starts at 0, so the first wait is is for `<multiplier>` seconds.
+
 | Attempt | Delay |
 | ------- | ----- |
 | 0       | 1     |
 | 1       | 2     |
 | 2       | 4     |
 
-The attempt counter starts at 0, so the first wait is is for `<multiplier>` seconds.
-
 ## Specifying durations
 
 Durations in `attempt` can include units, such as `5min`. Durations without units are assumed to be
-in seconds.
+in seconds. `300` would be interpreted as 300 seconds. Multiple units can be used together such as
+`1hr30m`. You may include whitespace, so `1hr 30m` is also valid.
 
 The following units are supported:
 
@@ -25,8 +26,6 @@ The following units are supported:
 - Milliseconds (`ms`)
 - Nanoseconds (`ns`)
 
-Multiple units can be used together such as `1hr 30m`.
-
 # Example
 
 ```bash

docs/src/backoff/fixed.md

@@ -11,7 +11,8 @@ Fixed delay is the default schedule. It sleeps for a constant amount of time bet
 ## Specifying durations
 
 Durations in `attempt` can include units, such as `5min`. Durations without units are assumed to be
-in DURATION.
+in seconds. `300` would be interpreted as 300 seconds. Multiple units can be used together such as
+`1hr30m`. You may include whitespace, so `1hr 30m` is also valid.
 
 The following units are supported:
 
@@ -21,16 +22,14 @@ The following units are supported:
 - Milliseconds (`ms`)
 - Nanoseconds (`ns`)
 
-Multiple units can be used together such as `1hr 30m`.
-
 # Example
 
 ```bash
 # Because it is the default, specifying `fixed` is optional
 attempt /bin/false
 attempt fixed /bin/false
 
-# Change the wait time from the default of 1 second to 15 DURATION
+# Change the wait time from the default of 1 second to 15 seconds
 attempt fixed -w 15s /bin/false
 attempt fixed --wait 15s /bin/false
 ```

docs/src/backoff/linear.md

@@ -13,7 +13,8 @@ Wait more time between attempts, using the following formula:
 ## Specifying durations
 
 Durations in `attempt` can include units, such as `5min`. Durations without units are assumed to be
-in DURATION.
+in seconds. `300` would be interpreted as 300 seconds. Multiple units can be used together such as
+`1hr30m`. You may include whitespace, so `1hr 30m` is also valid.
 
 The following units are supported:
 
@@ -23,8 +24,6 @@ The following units are supported:
 - Milliseconds (`ms`)
 - Nanoseconds (`ns`)
 
-Multiple units can be used together such as `1hr 30m`.
-
 # Example
 
 ```bash

docs/src/policy/output.md

@@ -1,8 +1,15 @@
 # Output predicates
 
-Output predicates examine the text written to stdout and stderr by the child command to determine
-whether to retry or stop. These predicates are useful when exit codes alone don't provide enough
-information about the failure condition.
+## Security
+
+If your application logs includes in it's output data from remote hosts or other untrusted sources,
+it is likely that attackers will be able to manipulate output predicates. Attackers will likely be
+able to trigger retry or stop predicates in inappropriate situations. If you are using regex
+predicates, attackers may be able to mount denial of service attacks by supplying
+[pathological inputs](https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS).
+Attackers may also launch denial of service attacks by causing the output to be large.
+
+Avoid using output predicates in untrusted environments.
 
 ## Performance
 

docs/src/timing/timeout.md

@@ -3,7 +3,8 @@
 ## Specifying durations
 
 Durations in `attempt` can include units, such as `5min`. Durations without units are assumed to be
-in seconds.
+in seconds. `300` would be interpreted as 300 seconds. Multiple units can be used together such as
+`1hr30m`. You may include whitespace, so `1hr 30m` is also valid.
 
 The following units are supported:
 
@@ -13,8 +14,6 @@ The following units are supported:
 - Milliseconds (`ms`)
 - Nanoseconds (`ns`)
 
-Multiple units can be used together such as `1hr 30m`.
-
 ## `-t --timeout <DURATION>`
 
 Kill the child command if it does not complete within the timeout. This prevents `attempt` from

docs/src/timing/wait.md

@@ -3,7 +3,8 @@
 ## Specifying durations
 
 Durations in `attempt` can include units, such as `5min`. Durations without units are assumed to be
-in seconds.
+in seconds. `300` would be interpreted as 300 seconds. Multiple units can be used together such as
+`1hr30m`. You may include whitespace, so `1hr 30m` is also valid.
 
 The following units are supported:
 
@@ -13,8 +14,6 @@ The following units are supported:
 - Milliseconds (`ms`)
 - Nanoseconds (`ns`)
 
-Multiple units can be used together such as `1hr 30m`.
-
 ## `-j --jitter <DURATION>`
 
 For a jitter value of `n`, adds a value in the interval `[0, n]` to the delay time. This is useful