firewall-objects

firewall-objects is a lightweight Rust framework for describing firewall entities—networks, transport services, and application indicators—so you can plug the building blocks into any policy engine, API, or control plane.

Highlights

• Network primitives – Parse hosts, CIDR ranges, IP spans, and FQDNs with deterministic ordering and doc-tested examples.
• Service catalog – Represent TCP/UDP/ICMP/IP entries, extend well-known aliases, and go from strings to strongly typed objects.
• Application descriptors – Express Layer-7 indicators (DNS suffixes, TLS SNI, HTTP hosts) with matching helpers and a sample catalog.
• Object store – Optional in-memory registry with JSON import/export (via the serde feature) for CRUD-style workflows.

Installation

[dependencies]
firewall-objects = "0.1.1"
# Optional JSON support
firewall-objects = { version = "0.1.1", features = ["serde"] }

Features

• serde (optional) – Enables serialization for all public structs/enums and activates JSON helpers in the objects module.

Networks: parsing and normalization

Use the ip module to normalize user input. Each call produces a deterministic Network variant.

use firewall_objects::ip::network::Network;
use std::str::FromStr;

let host = Network::from_str("192.0.2.10").unwrap();
let cidr = Network::from_str("2001:db8::/48").unwrap();
assert!(host < cidr); // ordering is stable

Services: transport definitions and aliases

TransportService represents TCP, UDP, ICMP, and IP protocol entries. Lookup helpers cover common aliases.

use firewall_objects::service::{registry, TransportService};
use std::str::FromStr;

let https = registry::lookup("https").unwrap();
assert_eq!(https.to_string(), "tcp/443");

let custom = TransportService::from_str("udp/6000").unwrap();
assert_eq!(custom, TransportService::udp(6000));

Applications: indicators and catalog lookups

Describe application behavior by combining DNS, TLS, and HTTP hints. The sample catalog is optional—bring your own definitions if you prefer.

use firewall_objects::service::{
    find_application,
    ApplicationMatchInput,
};

let github = find_application("github").unwrap();
let metadata = ApplicationMatchInput {
    dns_query: Some("status.github.com"),
    ..Default::default()
};
assert!(github.matches(&metadata));

Object store: managing firewall objects

The objects module provides a small storage layer with create/read/update/delete helpers. Everything is strongly typed; JSON I/O is available when the serde feature is enabled. Helper methods keep the API approachable.

use firewall_objects::objects::ObjectStore;
use firewall_objects::ip::network::NetworkObj;

let mut store = ObjectStore::new();
store
    .insert_network(NetworkObj::try_from(("app1", "192.0.2.10")).unwrap())
    .unwrap();

let network = store.network("app1").unwrap();
println!("{network:?}");

To serialize/deserialize via JSON (requires the serde feature):

# use firewall_objects::objects::{ObjectStore, ObjectKind};
# use firewall_objects::service::{ServiceObj, TransportService};
# #[cfg(feature = "serde")]
let mut store = ObjectStore::new();
# #[cfg(feature = "serde")]
{
    store.insert_service(ServiceObj::new("dns".into(), TransportService::udp(53))).unwrap();
    let json = store.to_json(ObjectKind::Service, "dns").unwrap();
    assert!(json.contains("\"dns\""));
}

Applications can be stored and matched as well:

use firewall_objects::objects::ObjectStore;
use firewall_objects::service::{
    ApplicationDefinition,
    ApplicationIndicators,
    ApplicationMatchInput,
    ApplicationObj,
    TransportService,
};

let mut store = ObjectStore::new();

let app = ApplicationObj {
    name: "metrics-ui".into(),
    category: "internal".into(),
    transports: vec![TransportService::tcp(443)],
    dns_suffixes: vec![".corp.local".into()],
    tls_sni_suffixes: vec![],
    http_hosts: vec!["metrics.corp.local".into()],
};
store.insert_application(app.clone()).unwrap();

let stored = store.application("metrics-ui").unwrap();
assert!(stored.matches(&ApplicationMatchInput {
    http_host: Some("metrics.corp.local"),
    ..Default::default()
}));

// Extend the catalog with your own definitions
pub const MY_APPS: &[ApplicationDefinition<'static>] = &[
    ApplicationDefinition {
        name: "internal-dashboard",
        category: "internal",
        transports: &[TransportService::tcp(8443)],
        indicators: ApplicationIndicators {
            dns_suffixes: &[".internal.corp"],
            tls_sni_suffixes: &[".internal.corp"],
            http_hosts: &["dashboard.internal.corp"],
        },
    },
];

Module Overview

• ip – Network entities and parsing utilities.
• service – Transport services, registries, and application descriptors.
• objects – Optional storage helpers with CRUD-style operations.
• error – Shared error type and result alias.

License

MIT. Contributions and feedback are always welcome!