Skip to main content

Crate windows_firewall

Crate windows_firewall 

Source
Expand description

Windows Firewall

Crates.io Build Status Dependency Status Documentation License MSRV codecov

A Rust crate for managing Windows Firewall rules and settings using the Windows API in Rust.

§Features

  • Create, modify, and delete firewall rules
  • Check firewall status and active profiles
  • Manage incoming and outgoing rules
  • Full control over rule properties:
    • Ports and protocols
    • Applications and services
    • Network interfaces
    • IP addresses
    • ICMP settings
    • Edge traversal
    • Security profiles

§Installation

Add this to your Cargo.toml:

[target.'cfg(windows)'.dependencies]
windows_firewall = "0.1.0"

§Usage Examples

§Creating and Managing Rules

use windows_firewall::{
    add_rule, remove_rule, rule_exists, update_rule, FirewallRule, FirewallRuleUpdate,
    Action, Direction, Protocol
};

// Create a new rule
let mut rule = FirewallRule::builder()
    .name("TestHTTPRule")
    .action(Action::Allow)
    .direction(Direction::In)
    .enabled(true)
    .description("Test HTTP rule")
    .protocol(Protocol::Tcp)
    .local_ports([80])
    .build();

// Add the rule
match add_rule(&rule) {
    Ok(_) => println!("Rule added successfully"),
    Err(e) => eprintln!("Failed to add rule: {}", e),
};

// Verify the rule exists
match rule_exists("TestHTTPRule") {
    Ok(exists) => println!("Rule exists: {}", exists),
    Err(e) => eprintln!("Failed to check rule: {}", e),
};

let updated_settings = FirewallRuleUpdate::builder()
    .enabled(false)
    .description("Updated test HTTP rule")
    .build();

// Update the rule
match update_rule("TestHTTPRule", &updated_settings) {
    Ok(_) => println!("Rule updated successfully"),
    Err(e) => eprintln!("Failed to update rule: {}", e),
};

// Remove the rule
match remove_rule("TestHTTPRule") {
    Ok(_) => println!("Rule removed successfully"),
    Err(e) => eprintln!("Failed to remove rule: {}", e),
};

§Another example of using struct methods

use windows_firewall::{
    FirewallRule, FirewallRuleUpdate,
    Action, Direction, Protocol
};

// Create a new firewall rule
let mut rule = FirewallRule::builder()
    .name("TestDNSServerRule")
    .action(Action::Allow)
    .direction(Direction::In)
    .enabled(true)
    .description("Test DNS Server rule")
    .protocol(Protocol::Udp)
    .local_ports([53])
    .build();

// Add the rule
match rule.add() {
    Ok(_) => println!("DNS Server rule added successfully"),
    Err(e) => eprintln!("Failed to add DNS Server rule: {}", e),
};

// Verify the rule exists
match rule.exists() {
    Ok(exists) => println!("Rule exists: {}", exists),
    Err(e) => eprintln!("Failed to check rule: {}", e),
};

let updated_settings = FirewallRuleUpdate::builder()
    .enabled(false)
    .description("Updated DNS Server rule")
    .build();

// Update the rule
match rule.update(&updated_settings) {
    Ok(_) => println!("DNS Server rule updated successfully"),
    Err(e) => eprintln!("Failed to update DNS Server rule: {}", e),
};

// Remove the rule
match rule.remove() {
    Ok(_) => println!("DNS Server rule removed successfully"),
    Err(e) => eprintln!("Failed to remove DNS Server rule: {}", e),
};

§Checking Firewall Status

use windows_firewall::{get_firewall_state, Profile};

match get_firewall_state(Profile::Public) {
    Ok(enabled) => println!("Firewall is {}", if enabled { "enabled" } else { "disabled" }),
    Err(e) => eprintln!("Failed to get firewall state: {}", e),
}

§Listing Firewall Rules

use windows_firewall::list_rules;

match list_rules() {
    Ok(rules) => {
        for rule in rules {
            println!("Rule: {}", rule.name());
            println!("  Direction: {:?}", rule.direction());
            println!("  Action: {:?}", rule.action());
            println!("  Enabled: {}", rule.enabled());
        }
    },
    Err(e) => eprintln!("Failed to list rules: {}", e),
}

§Requirements

  • Windows 7 or later
  • Administrative privileges for certain operations

§Support

For issues and questions:

§License

This project is licensed under either of

at your option.

Structs§

AddressRange
Struct representing an IP address range for firewall rules
FirewallRule
Represents a rule in the Windows Firewall.
FirewallRuleUpdate
Struct for updating Windows Firewall Rule
PortRange
Struct representing a port range for firewall rules

Enums§

Action
Represents the possible firewall actions in Windows
Address
Firewall address tokenS
AddressKeyword
Enum representing firewall address tokens Theses token can be uses uniquely in remote_addresses properties of firewall rules
Direction
Represents the possible firewall rule directions in Windows
InterfaceType
Enum representing different types of network interfaces.
Port
Firewall port token
PortKeyword
Enum representing firewall port keywords and values Theses token can be uses uniquely in local_ports properties of firewall rules
Profile
Represents the various Windows Firewall profiles.
Protocol
Represents the possible firewall protocols in Windows
WindowsFirewallError
Deriving common traits to automatically implement error handling functionality.

Functions§

add_rule
Adds a new firewall rule to the system.
add_rule_if_not_exists
Adds a new firewall rule to the system only if a rule with the same name doesn’t exist.
add_rule_or_update
Adds a new firewall rule to the system or updates an existing rule with the same name.
count_rules
Retrieves the total number of firewall rules.
enable_rule
Enables or disables an existing firewall rule.
get_active_profile
Retrieves the active firewall profile.
get_firewall_state
Retrieves the current state of the firewall for the specified profile.
get_rule
Retrieves the firewall rule with the specified name.
list_incoming_rules
Retrieves all incoming firewall rules as a list of FirewallRule objects.
list_outgoing_rules
Retrieves all outgoing firewall rules as a list of FirewallRule objects.
list_rules
Retrieves all the firewall rules as a list of FirewallRule objects.
remove_rule
Removes the specified firewall rule from the system.
rule_exists
Checks if a firewall rule with the given name exists.
set_firewall_state
Sets the firewall state (enabled or disabled) for the specified profile.
update_rule
Updates an existing firewall rule with new settings.