Skip to content

Update Docs #1382

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nasbench wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

Update Docs #1382

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 20 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# Splunk Attack Range v5

![Attack Range Logo](docs/attack_range.png)

The Splunk Attack Range builds instrumented cloud environments (AWS, Azure, GCP), simulates attacks, and forwards data into Splunk for detection development and testing.
Expand Down Expand Up @@ -28,8 +29,9 @@ The Splunk Attack Range builds instrumented cloud environments (AWS, Azure, GCP)
2. **Clone and start:**

```bash
git clone <repo-url>
cd attack_range_2
git clone https://github.com/splunk/attack_range
cd attack_range
docker compose -f docker/docker-compose.yml build --no-cache
docker compose -f docker/docker-compose.yml up
```

Expand All @@ -56,18 +58,24 @@ The Splunk Attack Range builds instrumented cloud environments (AWS, Azure, GCP)
## Ways to run

| Method | Use case |
|-------|----------|
|--------|----------|
| **Docker Compose** (recommended) | Run API + web app + optional CLI with one `docker compose`; no local Python/Ansible/Terraform. |
| **Web app** | Build, destroy, simulate, and share via the UI at port 4321. |
| **REST API** | Automate from scripts or CI; full OpenAPI docs at `/openapi/swagger`. |
| **CLI** | `attack_range.py build | destroy | simulate | share` for terminal-based workflows. |
| **CLI** | `attack_range.py build \| destroy \| simulate \| share` for terminal-based workflows. |

---

## Documentation

- **Full docs (Read the Docs):** [https://attack-range.readthedocs.io/](https://attack-range.readthedocs.io/en/latest/)
- Chapters: **Getting Started**, **Configuration**, **Networking**, **Sharing**, **Templates**, **Ansible Roles**
- Chapters:
- [Getting Started](https://attack-range.readthedocs.io/en/latest/getting-started.html)
- [Configuration](https://attack-range.readthedocs.io/en/latest/configuration.html)
- [Networking](https://attack-range.readthedocs.io/en/latest/networking.html)
- [Sharing](https://attack-range.readthedocs.io/en/latest/sharing.html)
- [Templates](https://attack-range.readthedocs.io/en/latest/templates.html)
- [Ansible Roles](https://attack-range.readthedocs.io/en/latest/ansible-roles.html)

---

Expand All @@ -79,7 +87,8 @@ The Splunk Attack Range builds instrumented cloud environments (AWS, Azure, GCP)

---

## Support
## Support

Please use the [GitHub issue tracker](https://github.com/splunk/attack_range/issues) to submit bugs or request features.

If you have questions or need support, you can:
Expand All @@ -90,16 +99,19 @@ If you have questions or need support, you can:

---

## Contributing
## Contributing

We welcome feedback and contributions from the community! Please see our [contribution guidelines](docs/CONTRIBUTING.md) for more information on how to get involved.

---

## Author
## Author(s)

* [Jose Hernandez](https://twitter.com/_josehelps)
* [Patrick Bareiß](https://twitter.com/bareiss_patrick)

## Contributors

* [Bhavin Patel](https://twitter.com/hackpsy)
* [Rod Soto](https://twitter.com/rodsoto)
* Russ Nolen
Expand Down
20 changes: 11 additions & 9 deletions docs/source/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,23 +18,25 @@ Docker Compose runs the API, web app, and (optionally) the CLI without installin
1. **Start the stack:**

```bash
cd attack_range_2
docker compose -f docker/docker-compose.yml up
git clone https://github.com/splunk/attack_range.git
cd attack_range
docker compose -f docker/docker-compose.yml build --no-cache
docker compose -f docker/docker-compose.yml up
```

This starts:

- **API** on port **4000**
- **Web app** on port **4321**
- The **API** on port **4000**
- The **Web app** on port **4321**

2. **Open the web app:** [http://localhost:4321](http://localhost:4321)

3. **Build your first range:**

- Choose a template (e.g. **aws/splunk_minimal_aws**).
- Click build. The backend runs **Phase 1** (VPN infrastructure).
- When status is **Waiting for VPN**, download the WireGuard client config.
- Connect to the VPN using WireGuard (Desktop or mobile).
- When status changes to **Waiting for VPN**, download/copy the WireGuard client config.
- Connect to the VPN using WireGuard (Desktop or mobile). If you are using WSL2 make sure to install WireGuard on the host machine not the WSL instance.
- Click **Continue build** to run **Phase 2** (lab: Splunk, Windows, etc.).

4. **Optional — CLI in Docker:**
Expand Down Expand Up @@ -107,9 +109,9 @@ Config can be a path or an attack range ID (e.g. `uuid.yml` in `config/`). If om

Attack Range uses a two-phase build so the lab is only reachable over VPN:

1. **Phase 1 (VPN):** Terraform creates the network and a router; Ansible configures WireGuard on the router and generates a client config. Status becomes **wait_for_vpn**.
2. **You:** Download the WireGuard config, connect with the WireGuard client.
3. **Phase 2 (Lab):** You trigger the continuation (in the app or with a second API call or by answering the CLI prompt). Ansible provisions Splunk, Windows, Kali, etc. over the VPN. Status becomes **running**.
1. **Phase 1 (VPN):** Terraform creates the network and a router; Ansible configures WireGuard on the router and generates a client config. Status becomes `wait_for_vpn`.
2. **You:** Download or copy the WireGuard config, connect with the WireGuard client.
3. **Phase 2 (Lab):** You trigger the continuation (in the app or with a second API call or by answering the CLI prompt). Ansible provisions Splunk, Windows, Kali, etc. over the VPN. Status becomes `running`.

This keeps lab IPs (e.g. 10.0.2.x) off the public internet.

Expand Down