Skip to content

Commit 26dfa5d

Browse files
brikis98brikis98
committed
Auto-generate docs for release v0.4.20 [ci skip]
1 parent d2b2676 commit 26dfa5d

12 files changed

+150
-0
lines changed

‎_ci/output-debug-values.sh

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
2+
# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/_ci/output-debug-values.sh>.
4+
# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

‎examples/fail2ban/README.md

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
**Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
2+
We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/examples/fail2ban/README.md>.
4+
If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!
5+
6+
# Fail2Ban Module Example
7+
8+
This is an example of how to use the [fail2ban module](/modules/fail2ban) to configure a Linux server to
9+
automatically ban malicious ip addresses. The example contains a [Packer](https://www.packer.io/) template that creates
10+
either an Ubuntu or Amazon Linux AMI and installs and configures `fail2ban` on them.
11+
12+
## Quick start
13+
14+
To build the AMIs:
15+
16+
1. Install [Packer](https://www.packer.io/)
17+
1. Set your [GitHub access token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/) as
18+
the environment variable `GITHUB_OAUTH_TOKEN`.
19+
1. Run `packer build fail2ban-amazon-example.json` or `packer build fail2ban-ubuntu-example.json`

‎examples/fail2ban/fail2ban-example.json

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
// **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
2+
// We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
// If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/examples/fail2ban/fail2ban-example.json>.
4+
// If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

‎modules/fail2ban/README.md

+91
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
**Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
2+
We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/modules/fail2ban/README.md>.
4+
If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!
5+
6+
# Fail2Ban Module
7+
8+
This module can configure a Linux server to automatically ban malicious ip addresses from connecting to the server
9+
via SSH. This module currently supports Ubuntu and Amazon Linux (using [fail2ban](https://www.fail2ban.org)).
10+
11+
The module also optionally creates CloudWatch Metrics to track the number of Banned and Unbanned IP Addresses per AWS
12+
Instance.
13+
14+
## How do you use this module?
15+
16+
#### Example
17+
18+
See the [fail2ban example](/examples/fail2ban) for an example of how to use this module.
19+
20+
#### Installation
21+
22+
```
23+
gruntwork-install --module-name fail2ban --tag v0.0.1 --repo https://github.com/gruntwork-io/module-security
24+
```
25+
26+
#### Configuration Options
27+
You can configure several options to control the behavior of fail2ban. If you're using gruntwork-install, you'll need to
28+
use the --module-param option, such as gruntwork-install --module fail2ban --module-param ban-time=3600).
29+
30+
|Option|Description|Required|Default|
31+
|---|---|---|---|
32+
|--logging-level|The logging level for fail2ban. 1=ERROR, 2=WARN, 3=INFO, 4=DEBUG.|Optional|3=INFO|
33+
|--target|The target for fail2ban. STDOUT, STDERR, SYSLOG, /path/to/file. |Optional|SYSLOG|
34+
|--ignore-ip|The space delimited list of ip addresses or CIDR blocks for fail2ban to ignore.|Optional|127.0.0.1/8|
35+
|--ban-time|The amount of time in seconds a malicious ip address will be banned for.|Optional|86400|
36+
|--find-time|The time window in seconds to look at for failures|Optional|600|
37+
|--max-retry|The number of failures (eg. password failures) that constitute a bad actor|Optional|5|
38+
|--backend|The method used to determine if a logfile contents have changed. Possible values are: auto, pyinotify, gamin, polling|Optional|auto|
39+
|--ssh-port|The port the ssh daemon being protected is running on|Optional|22 (ssh)|
40+
|--no-cloudwatch-metrics|Flag to disable creation of cloudwatch metrics|Optional||
41+
42+
#### CloudWatch Metrics
43+
By default the script will report the count of the number of IP Addresses Banned and Unbanned to the `BannedIPAddresses`
44+
and `UnbannedIPAddresses` CloudWatch metrics in the `Gruntwork/Fail2Ban` namespace. This namespace can be changed using
45+
the `--cloudwatch-namespace`switch.
46+
47+
CloudWatch Metric reporting can be disabled all together during installation using the `--no-cloudwatch-metrics` switch.
48+
49+
##### Permissions
50+
If the option to install CloudWatch Metrics is selected (default behavior), it is assumed that the EC2 Instance has
51+
permissions to publish metric data to the CloudWatch API. This can be done by attaching a policy to the EC2 Instance's
52+
IAM Role. The permissions necessary are:
53+
54+
```json
55+
{
56+
"Version": "2012-10-17",
57+
"Statement": [
58+
{
59+
"Sid": "Stmt1493296209000",
60+
"Effect": "Allow",
61+
"Action": [
62+
"cloudwatch:PutMetricData"
63+
],
64+
"Resource": [
65+
"*"
66+
]
67+
}
68+
]
69+
}
70+
```
71+
72+
##### Configure the Fail2Ban CloudWatch Action on your EC2 Instances
73+
74+
In order for the EC2 Instance to send metric data to CloudWatch sucessfully, it needs certain data from the EC2 instance.
75+
76+
When your EC2 Instances are booting up, they should run the `configure-fail2ban-cloudwatch.sh` script, which will configure
77+
fail2ban to send data to CloudWatch. The script supports one command line option:
78+
79+
* `--cloudwatch-namespace`: The namespace used to define the cloudwatch metrics. Default value is 'Gruntwork/Fail2Ban'. Optional.
80+
81+
The best way to run a script during boot is to put it in [User
82+
Data](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html#user-data-shell-scripts). Here's an example:
83+
84+
```bash
85+
#!/bin/bash
86+
/etc/user-data/cloudwatch-fail2ban-cloudwatch/cloudwatch-fail2ban-cloudwatch.sh --cloudwatch-namespace Acme/Fail2Ban
87+
```
88+
89+
#### TODO
90+
91+
* Add support for protocols/services other than ssh

‎modules/fail2ban/install-scripts/cloudwatch-metric.conf

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
2+
# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/modules/fail2ban/install-scripts/cloudwatch-metric.conf>.
4+
# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

‎modules/fail2ban/install-scripts/configure-fail2ban

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
**Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
2+
We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/modules/fail2ban/install-scripts/configure-fail2ban>.
4+
If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

‎modules/fail2ban/install-scripts/fail2ban.local

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
**Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
2+
We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/modules/fail2ban/install-scripts/fail2ban.local>.
4+
If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

‎modules/fail2ban/install-scripts/jail.amazon.local

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
**Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
2+
We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/modules/fail2ban/install-scripts/jail.amazon.local>.
4+
If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

‎modules/fail2ban/install-scripts/jail.ubuntu.local

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
**Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
2+
We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/modules/fail2ban/install-scripts/jail.ubuntu.local>.
4+
If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

‎modules/fail2ban/install.sh

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
2+
# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/modules/fail2ban/install.sh>.
4+
# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

‎modules/fail2ban/user-data-scripts/configure-fail2ban-cloudwatch.sh

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
2+
# We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
# If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/modules/fail2ban/user-data-scripts/configure-fail2ban-cloudwatch.sh>.
4+
# If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

‎test/fail2ban_test.go

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
// **Note**: This public repo contains the documentation for the private GitHub repo <https://github.com/gruntwork-io/module-security>.
2+
// We publish the documentation publicly so it turns up in online searches, but to see the source code, you must be a Gruntwork customer.
3+
// If you're already a Gruntwork customer, the original source for this file is at: <https://github.com/gruntwork-io/module-security/blob/master/test/fail2ban_test.go>.
4+
// If you're not a customer, contact us at <[email protected]> or <http://www.gruntwork.io> for info on how to get access!

0 commit comments

Comments
 (0)