push_packet/lib.rs
1#![deny(missing_docs)]
2#![deny(rustdoc::all)]
3#![deny(clippy::pedantic)]
4#![deny(clippy::undocumented_unsafe_blocks)]
5#![deny(clippy::multiple_unsafe_ops_per_block)]
6#![deny(clippy::as_conversions)]
7#![allow(clippy::cast_possible_truncation)]
8//! push-packet is a high-level, extensible packet routing library built on eBPF with aya. It is
9//! intended to be a simple, yet flexible foundation for traffic analysis applications and
10//! network-stack bypass.
11//!
12//! # Example: Tap into a network interface, and copy all packets to userspace.
13//! ```no_run
14//! # use push_packet::{Tap, rules::{Rule, Action}};
15//! # fn main() -> Result<(), push_packet::Error> {
16//! let mut tap = Tap::builder("wlp3s0")
17//! .rule(Rule::source_cidr("0.0.0.0/0").action(Action::Copy { take: None }))
18//! .build()?;
19//!
20//! let mut rx = tap.copy_receiver()?;
21//! while let Ok(event) = rx.recv() {
22//! println!("Received packet of length {}", event.packet_len());
23//! }
24//! # Ok(())
25//! # }
26//! ```
27//! # Example: Tap into an interface, add and remove rules dynamically.
28//! ```no_run
29//! # use push_packet::{Tap, rules::{Rule, Action, Protocol}, CopyConfig};
30//! # fn main() -> Result<(), push_packet::Error> {
31//! let mut tap = Tap::builder("wlp3s0")
32//! // Set force_enabled on the copy config so we can use copy rules later.
33//! .copy_config(CopyConfig::default().force_enabled())
34//! .build()?;
35//!
36//! // call add_rule to get a RuleId
37//! let drop_rule_id = tap.add_rule(
38//! Rule::protocol(Protocol::Tcp)
39//! .source_cidr("127.0.0.1")
40//! .source_port(3000..4000)
41//! .action(Action::Drop),
42//! )?;
43//!
44//! // [traffic dropped]
45//!
46//! // Remove a rule with RuleId
47//! tap.remove_rule(drop_rule_id)?;
48//!
49//! // Read some traffic instead
50//! tap.add_rule(
51//! Rule::source_cidr("127.0.0.1")
52//! .source_port(3001)
53//! .action(Action::COPY_ALL),
54//! )?;
55//!
56//! let mut rx = tap.copy_receiver()?;
57//! while let Ok(event) = rx.recv() {
58//! println!("Received packet of length {}", event.packet_len());
59//! }
60//!
61//! # Ok(())
62//! # }
63//! ```
64
65mod af_xdp;
66mod array_ext;
67mod cast;
68mod ebpf;
69mod error;
70mod filter;
71mod interface;
72mod loader;
73mod relay;
74mod tap;
75
76pub mod channels;
77pub mod engine;
78pub mod events;
79pub mod rules;
80
81pub use channels::ChannelError;
82pub use error::Error;
83pub use interface::Interface;
84pub use loader::Loader;
85pub use push_packet_common::FrameKind;
86pub use rules::RuleError;
87pub use tap::{CopyConfig, RouteConfig, Tap, TapBuilder};