rustnetconf

A Rust network automation platform: async NETCONF client library, YANG code generation, vendor profiles, connection pooling, and a Terraform-like CLI for declarative network config management.

Built on tokio, russh, and rustls — pure Rust, no OpenSSL, no libssh2.

Workspace

Crate	Description
rustnetconf	Async NETCONF 1.0/1.1 client library
rustnetconf-yang	YANG model code generation (compile-time config validation)
rustnetconf-cli	Terraform-like CLI tool (`netconf` binary)

RFC Support

RFC	Feature	Status
RFC 6241	Network Configuration Protocol (NETCONF)	✅ supported
RFC 6242	NETCONF over SSH	✅ supported
RFC 7589	NETCONF over TLS	✅ supported (feature flag `tls`) — needs physical SRX or non-vSRX for TLS test
RFC 5277	Event Notifications	✅ supported — tested on Junos 24.4 vSRX (subscription + capability; interleave limited by device)
RFC 5717	Partial Lock RPC	💡 planned
RFC 8071	NETCONF Call Home	💡 planned
RFC 6243	With-defaults Capability	💡 planned
RFC 6022	YANG Module for NETCONF Monitoring	💡 planned
RFC 8526	NETCONF Extensions for NMDA	💡 planned
RFC 6470	NETCONF Base Notifications	💡 planned
RFC 8040	RESTCONF	💡 planned

CLI Tool — `netconf`

Declarative network config management. Write desired state as XML files, the CLI diffs against the device and applies changes with confirmed-commit safety.

netconf init                    # Create project skeleton
netconf plan spine-01           # Show what would change (colored diff)
netconf apply spine-01          # Apply with confirmed-commit (auto-revert on timeout)
netconf confirm spine-01        # Make changes permanent
netconf rollback spine-01       # Revert to saved state
netconf get spine-01            # Fetch running config
netconf validate spine-01       # Dry-run validation

Project Structure

my-network/
├── inventory.toml              # Device connection details
├── desired/
│   └── spine-01/
│       ├── interfaces.xml      # Desired interface config
│       └── system.xml          # Desired system config
└── .netconf/state/             # Rollback snapshots (auto-managed)

inventory.toml

[defaults]
confirm_timeout = 60

[devices.spine-01]
host = "10.0.0.1:830"
username = "admin"
key_file = "~/.ssh/id_ed25519"
# vendor auto-detected from device hello

Library — Quick Start

[dependencies]
rustnetconf = { git = "https://github.com/fastrevmd-lab/rustnetconf.git" }
tokio = { version = "1", features = ["full"] }

For TLS transport (RFC 7589), enable the tls feature:

[dependencies]
rustnetconf = { git = "https://github.com/fastrevmd-lab/rustnetconf.git", features = ["tls"] }

Fetch running config

use rustnetconf::{Client, Datastore};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = Client::connect("10.0.0.1:830")
        .username("admin")
        .key_file("~/.ssh/id_ed25519")
        .connect()
        .await?;

    let config = client.get_config(Datastore::Running).await?;
    println!("{config}");

    client.close_session().await?;
    Ok(())
}

Edit config (full round trip)

use rustnetconf::{Client, Datastore, DefaultOperation};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = Client::connect("10.0.0.1:830")
        .username("admin")
        .password("secret")
        .connect()
        .await?;

    client.lock(Datastore::Candidate).await?;

    client.edit_config(Datastore::Candidate)
        .config("<interface><name>ge-0/0/0</name><description>uplink</description></interface>")
        .default_operation(DefaultOperation::Merge)
        .send()
        .await?;

    client.validate(Datastore::Candidate).await?;
    client.commit().await?;
    client.unlock(Datastore::Candidate).await?;

    client.close_session().await?;
    Ok(())
}

Connect over TLS (RFC 7589)

Note: vSRX 24.4 has a known TLS handshake issue where the PKI engine cannot present a self-signed certificate chain. TLS testing requires a physical SRX, MX, or EX device with a CA-signed certificate. The code compiles and passes unit tests but has not been validated against a live TLS-capable device.

use rustnetconf::{Client, TlsConfig, Datastore};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = TlsConfig {
        host: "10.0.0.1".into(),
        ca_cert: Some("ca.pem".into()),
        client_cert: Some("client.pem".into()),
        client_key: Some("client-key.pem".into()),
        ..Default::default()
    };

    let mut client = Client::connect_tls(config).connect().await?;
    let config = client.get_config(Datastore::Running).await?;
    println!("{config}");

    client.close_session().await?;
    Ok(())
}

Event notifications (RFC 5277)

use rustnetconf::{Client, Datastore};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = Client::connect("10.0.0.1:830")
        .username("admin")
        .password("secret")
        .connect()
        .await?;

    // Subscribe to NETCONF event stream
    client.create_subscription(Some("NETCONF"), None, None, None).await?;

    // Block waiting for notifications
    while let Some(notif) = client.recv_notification().await? {
        println!("[{}] {}", notif.event_time, notif.event_xml);
    }

    Ok(())
}

Note: Some devices (e.g., Junos vSRX 24.4) advertise :interleave but do not respond to RPCs on a session with an active subscription. On these devices, use a dedicated session for notifications and a separate session for RPCs. Notifications arriving during RPCs on interleave-capable devices are automatically buffered and available via drain_notifications().

Connection pooling

use rustnetconf::pool::{DevicePool, DeviceConfig};
use rustnetconf::transport::ssh::SshAuth;
use rustnetconf::Datastore;

let pool = DevicePool::builder()
    .max_connections(50)
    .add_device("spine-01", DeviceConfig {
        host: "10.0.0.1:830".into(),
        username: "admin".into(),
        auth: SshAuth::KeyFile { path: "~/.ssh/id_ed25519".into(), passphrase: None },
        vendor: None, // auto-detect
    })
    .build();

let mut conn = pool.checkout("spine-01").await?;
let config = conn.get_config(Datastore::Running).await?;
// connection auto-returned to pool on drop

Features

NETCONF Client

Async-first — tokio-based, push config to 500 devices concurrently
SSH + TLS transports — SSH (RFC 6242) by default, TLS (RFC 7589) via tls feature flag
NETCONF 1.0 + 1.1 — EOM and chunked framing with auto-negotiation
All core RPCs — get, get-config, edit-config, lock/unlock, commit, validate, close/kill-session, discard-changes
Confirmed commit — auto-rollback safety net (RFC 6241 §8.4)
Event notifications — create-subscription, inline notification demux, buffered drain/recv API (RFC 5277)
CommitUnknown detection — distinguishes "commit failed" from "maybe committed, connection lost"
Stale lock recovery — lock_or_kill_stale() kills crashed sessions holding locks
Framing mismatch detection — catches firmware bugs where devices send wrong framing

Vendor Profiles

Auto-detection from device <hello> capabilities
Junos — config wrapping, namespace normalization, discard-before-close
Generic — standard RFC 6241 for any compliant device
Extensible — implement VendorProfile trait for custom vendors

Connection Pool

Tokio semaphore-based concurrency limiting
Checkout with timeout (no blocking forever)
Auto-checkin on drop, broken connections discarded
Connection reuse from idle pool

YANG Code Generation

Build-time generation from .yang model files via libyang2
Typed Rust structs with serde Serialize/Deserialize
Correct type mapping (string, bool, uint32, etc.)
Bundled IETF models: ietf-interfaces, ietf-ip, ietf-yang-types, ietf-inet-types

Authentication

Method	Transport	Builder API
Password	SSH	`.password("secret")`
Key file	SSH	`.key_file("~/.ssh/id_ed25519")`
SSH agent	SSH	`.ssh_agent()`
Server-only TLS	TLS	`TlsConfig { ca_cert, .. }`
Mutual TLS (mTLS)	TLS	`TlsConfig { client_cert, client_key, .. }`

Error Handling

Layered errors matching the protocol stack:

match result {
    Err(NetconfError::Transport(e)) => { /* SSH/TLS connection issues */ }
    Err(NetconfError::Framing(e))   => { /* Protocol framing errors */ }
    Err(NetconfError::Rpc(e))       => { /* Device rejected RPC (all 7 RFC fields parsed) */ }
    Err(NetconfError::Protocol(e))  => { /* Capability/session errors */ }
    Ok(response) => { /* Success */ }
}

Supported Operations

Operation	RFC 6241	Status
`get`	§7.7	Done
`get-config`	§7.1	Done
`edit-config`	§7.2	Done
`lock` / `unlock`	§7.4-7.5	Done
`close-session`	§7.8	Done
`kill-session`	§7.9	Done
`commit`	§8.4	Done
`confirmed-commit`	§8.4	Done
`validate`	§8.6	Done
`discard-changes`	§8.3	Done

Testing

140+ tests across the workspace:

Unit tests — framing, RPC serialization, capability parsing, vendor profiles, diff engine, inventory parsing
Mock transport tests — session state machine, CommitUnknown detection, lock recovery
Integration tests — 32 tests against a live Juniper vSRX including full edit-config round trips, vendor auto-detection, connection pooling, and concurrent sessions

cargo test --workspace                    # Run all tests
cargo test --test integration_vsrx        # Run vSRX integration tests only
SKIP_INTEGRATION=1 cargo test             # Skip tests requiring a device

Security

Known Issues

RSA timing sidechannel (RUSTSEC-2023-0071) — The rsa crate (transitive dependency via russh → internal-russh-forked-ssh-key → rsa) has a known timing sidechannel that could theoretically allow RSA key recovery. No upstream fix is available. Mitigation: Use Ed25519 or ECDSA keys instead of RSA for SSH authentication.
Credentials not zeroized in memory — Passwords and key passphrases are stored as String, which is not securely zeroed on drop. Credentials may persist in process memory until overwritten. Mitigation: Prefer SSH agent authentication (ssh_agent()) over inline passwords/passphrases, and avoid core dumps in production.
Debug logs may contain file paths — When SSH key file loading fails, the key file path is included in tracing::debug! output. This is not exposed at info/warn/error levels. Mitigation: Disable debug-level logging in production, or filter rustnetconf::transport logs.

Security Features

SSH host key verification — Use host_key_verification(HostKeyVerification::Fingerprint("SHA256:...")) to pin a device's host key and prevent MITM attacks. Default is AcceptAll (with a logged warning), consistent with most network automation tools.
XML attribute escaping — All message-id values are escaped to prevent XML attribute injection.
Read buffer limits — Session read buffers are capped at 100 MB to prevent memory exhaustion from malformed device responses.
Typed error hierarchy — Structured error types (ChannelClosed, SessionExpired, MessageIdMismatch) enable precise error handling without string matching.
No unsafe code — The entire codebase uses safe Rust.

Security Best Practices

Use Ed25519 SSH keys (not RSA) for device authentication
Set host_key_verification(HostKeyVerification::Fingerprint(...)) in production
Prefer SSH agent auth over inline passwords
Store credentials in inventory.toml with restricted file permissions (chmod 600)
Run the CLI on trusted management networks with direct device connectivity
Use confirmed-commit (the default for netconf apply) so the device auto-reverts if something goes wrong
Disable debug-level logging in production environments

To report a security vulnerability, please open an issue on GitHub.

Dependencies

Crate	Version	Purpose
`async-trait`	0.1.89	Async trait support
`futures`	0.3.32	Async combinators
`quick-xml`	0.37.5	XML parsing (NETCONF RPC encode/decode)
`russh`	0.60.0	SSH transport (pure Rust, no libssh2)
`thiserror`	2.0.18	Error derive macros
`tokio`	1.50.0	Async runtime
`tracing`	0.1.44	Structured logging/tracing

Dev-only:

Crate	Version	Purpose
`tokio-test`	0.4.5	Async test utilities
`tracing-subscriber`	0.3.23	Log subscriber for tests

License

MIT OR Apache-2.0

Contributing

Contributions welcome! See ARCHITECTURE.md for the codebase design and TODOS.md for tracked work items.

Name		Name	Last commit message	Last commit date
Latest commit History 54 Commits
examples		examples
rustnetconf-cli		rustnetconf-cli
rustnetconf-yang		rustnetconf-yang
src		src
tests		tests
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
CLAUDE.md		CLAUDE.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE-APACHE		LICENSE-APACHE
LICENSE-MIT		LICENSE-MIT
README.md		README.md
TODOS.md		TODOS.md

Folders and files

Latest commit

History

Repository files navigation

rustnetconf

Workspace

RFC Support

CLI Tool — netconf

Project Structure

inventory.toml

Library — Quick Start

Fetch running config

Edit config (full round trip)

Connect over TLS (RFC 7589)

Event notifications (RFC 5277)

Connection pooling

Features

NETCONF Client

Vendor Profiles

Connection Pool

YANG Code Generation

Authentication

Error Handling

Supported Operations

Testing

Security

Known Issues

Security Features

Security Best Practices

Dependencies

License

Contributing

About

Topics

Resources

License

Licenses found

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

CLI Tool — `netconf`

Packages