> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/resilience-testing/chaos-engineering/faults/chaos-fault-categories/windows/windows-blackhole-chaos.md).

# Windows blackhole chaos

Windows blackhole chaos is a Windows chaos fault that blocks all network traffic from the target Windows VM to the destinations listed in `DESTINATION_HOSTS` and `IP_ADDRESSES` for `DURATION`, then removes the block. The fault runs through the Windows chaos agent installed as a service on the target VM. Use `SERVER_HOST` to spare the target VM's own management endpoint when the chaos pod needs to reach the VM during the experiment.

Use this fault to test how a workload on a Windows VM behaves when a downstream dependency is unreachable: whether retries and timeouts work, whether circuit breakers open correctly, whether the workload fails over to a backup endpoint, and whether monitoring detects the regression within the alerting SLA.

{% hint style="info" %}
**RUN YOUR FIRST EXPERIMENT**

If you have not configured the chaos infrastructure yet, go to [Quickstart](/resilience-testing/chaos-engineering/new-to-chaos-engineering/quickstart.md) to install the chaos infrastructure and run an experiment end to end.
{% endhint %}

***

### Use cases <a href="#use-cases" id="use-cases"></a>

* **Dependency outage:** When a downstream dependency is unreachable, does the caller honour its timeout and circuit-breaker policy?
* **Backup endpoint failover:** Does the workload fail over to a backup endpoint inside the SLA?
* **Alert fidelity:** Do downstream alerts fire inside the alerting SLA?

***

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* **Windows chaos infrastructure:** Install the chaos agent on the target VM. Go to [Windows requirements and security considerations](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/windows/windows-chaos-permissions.md).
* **Administrator privileges:** Blackhole chaos is an Advanced fault and requires the agent to run as administrator.
* **Destination known:** You know the destination hosts or IPs to block.

***

### Supported environments <a href="#supported-environments" id="supported-environments"></a>

| Platform                                                  | Support status                                                                                                                                                                                                                                                                                         |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Windows Server VMs with the Windows chaos agent installed | Supported                                                                                                                                                                                                                                                                                              |
| Linux VMs                                                 | Not supported (use [VMware network loss](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/vmware/linux/vmware-network-loss.md) or [Linux network loss](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/linux/linux-network-loss.md) to approximate a blackhole) |

***

### Permissions required <a href="#permissions-required" id="permissions-required"></a>

This fault is classified as **Advanced**. The chaos agent must be installed and running with administrator privileges to mutate Windows Firewall (or equivalent) rules.

***

### Fault tunables <a href="#fault-tunables" id="fault-tunables"></a>

**Chaos parameters**

| Tunable             | Description                                                                                                                                                                                                      | Default |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `DURATION`          | Total duration of the fault as a Go duration string (for example `30s`, `5m`).                                                                                                                                   | `30s`   |
| `DESTINATION_HOSTS` | Comma-separated list of destination hostnames to block.                                                                                                                                                          | `""`    |
| `IP_ADDRESSES`      | Comma-separated list of destination IPs/CIDRs to block.                                                                                                                                                          | `""`    |
| `SERVER_HOST`       | Hostname/IP of an endpoint to exclude from the block (typically your control-plane endpoint).                                                                                                                    | `""`    |
| `RAMP_TIME`         | Wait period in seconds before and after the fault. Go to [ramp time](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/common-tunables-for-all-faults.md#ramp-time) to read how it is applied. | `0`     |

Provide at least one of `DESTINATION_HOSTS` or `IP_ADDRESSES`. To block all egress traffic to every destination, leave both empty (in which case `SERVER_HOST` is the only sanctioned reachable endpoint).

Tunables that apply to every fault are documented in [common tunables for all faults](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/common-tunables-for-all-faults.md).

***

### Fault execution in brief <a href="#fault-execution-in-brief" id="fault-execution-in-brief"></a>

The Windows chaos agent on the target VM installs firewall rules that drop traffic to each host in `DESTINATION_HOSTS` and each IP/CIDR in `IP_ADDRESSES` (excluding `SERVER_HOST`) for `DURATION`, then removes the rules.

***

### Expected behavior during fault execution <a href="#expected-behavior-during-fault-execution" id="expected-behavior-during-fault-execution"></a>

* All egress traffic from the VM to the blocked destinations is dropped.
* Callers may see timeouts and connection failures.
* After the duration ends, the firewall rules are removed and connectivity returns to baseline.

{% hint style="info" %}
**WHEN THE FAULT ENDS**

The chaos agent removes the firewall rules. Connectivity to the blocked destinations returns to baseline within seconds.
{% endhint %}

#### Signals to watch <a href="#signals-to-watch" id="signals-to-watch"></a>

* **Reachability:** Use a [command probe](/resilience-testing/chaos-testing/probes/command-probe.md) running `Test-NetConnection <host>` and assert success after the fault ends.
* **Workload:** Use an [HTTP probe](/resilience-testing/chaos-engineering/use-chaos-engineering/probes/http-probe.md) and assert error budget is respected.

***

### Verify the fault execution effect <a href="#verify-the-fault-execution-effect" id="verify-the-fault-execution-effect"></a>

1. **During the chaos window, from the target VM run `Test-NetConnection <DESTINATION_HOSTS_entry>` in PowerShell.**

   The probe should report unreachable.
2. **Inspect the Windows Firewall rules.**

   ```powershell
   Get-NetFirewallRule | Where-Object DisplayName -like "*HCE*"
   ```

   The chaos rules should be present during the window and removed afterwards.

***

### Recovery and cleanup <a href="#recovery-and-cleanup" id="recovery-and-cleanup"></a>

* **End of duration:** The chaos agent removes the firewall rules.
* **Abort:** Stopping the experiment also removes the rules.
* **Manual recovery:** If the rules survive, remove them with `Remove-NetFirewallRule -DisplayName "*HCE*"` as administrator.

***

### Limitations <a href="#limitations" id="limitations"></a>

* **Outbound only:** The fault blocks outbound traffic from the VM. Inbound is unaffected.
* **DNS at start:** `DESTINATION_HOSTS` is resolved when the rules are installed. DNS changes during the chaos window are not picked up.
* **Administrator required:** This is an Advanced fault and requires the agent to run as administrator.

***

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

<details>

<summary>Windows blackhole chaos has no observable effect in Harness Chaos Engineering</summary>

Confirm the firewall rules were installed (Get-NetFirewallRule | Where-Object DisplayName -like \*HCE\*). Confirm DESTINATION\_HOSTS resolves to the IP the workload actually contacts. If your workload uses a different egress path (proxy, VPN), the rule may not match.

</details>

<details>

<summary>Windows blackhole chaos fails with access denied</summary>

The chaos agent must run as administrator to mutate firewall rules. Reinstall the agent as administrator and retry.

</details>

***

### Related faults <a href="#related-faults" id="related-faults"></a>

* [Windows network latency](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/windows/windows-network-latency.md): Add latency instead of blocking traffic.
* [Windows network loss](/resilience-testing/chaos-engineering/faults/chaos-fault-categories/windows/windows-network-loss.md): Drop a percentage of packets instead of blocking entirely.