STRLCPY/ebpfguard

Readme: embedd an example in readme. Move lsm section up
Tomasz Jonak committed 1 year ago

12ca746b

1 parent cd90c568

Revision indexing in progress... (symbol navigation in revisions will be accurate after indexed)

■ ■ ■ ■ ■ ■

README.md

		skipped 30 lines
31	31		It's based on eBPF and [Aya](https://aya-rs.dev) library, but takes away
32	32		the need to use them directly.
33	33
	34	+	## Usage example
	35	+
	36	+	Deny mount operation for all users.
	37	+
	38	+	```rust
	39	+	const BPF_MAPS_PATH: &str = "/sys/fs/bpf/example_sb_mount";
	40	+
	41	+	// Create a directory where ebpfguard policy manager can store its BPF
	42	+	// objects (maps).
	43	+	std::fs::create_dir_all(BPF_MAPS_PATH)?;
	44	+
	45	+	// Create a policy manager.
	46	+	let mut policy_manager = PolicyManager::new(BPF_MAPS_PATH)?;
	47	+
	48	+	// Attach the policy manager to the mount LSM hook.
	49	+	let mut sb_mount = policy_manager.attach_sb_mount()?;
	50	+
	51	+	// Get the receiver end of the alerts channel (for the `file_open` LSM
	52	+	// hook).
	53	+	let mut sb_mount_rx = sb_mount.alerts().await?;
	54	+
	55	+	// Define policies which deny mount operations for all processes (except
	56	+	// for the specified subject, if defined).
	57	+	sb_mount
	58	+	.add_policy(SbMount {
	59	+	subject: PolicySubject::All,
	60	+	allow: false,
	61	+	})
	62	+	.await?;
	63	+
	64	+	if let Some(alert) = sb_mount_rx.recv().await {
	65	+	info!(
	66	+	"sb_mount alert: pid={} subject={}",
	67	+	alert.pid, alert.subject
	68	+	);
	69	+	}
	70	+	```
	71	+
	72	+	Imports and cargo file are available in [example source code](examples/readme_mount). For more examples check out [EXAMPLES.md](doc/EXAMPLES.md).
	73	+
	74	+
	75	+	## Supported LSM hooks
	76	+
	77	+	LSM hooks supported by Ebpfguard are:
	78	+
	79	+	* [`bprm_check_security`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L62)
	80	+	* [`file_open`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L620)
	81	+	* [`sb_mount`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L128)
	82	+	* [`sb_remount`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L147)
	83	+	* [`sb_umount`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L159)
	84	+	* [`socket_bind`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L904)
	85	+	* [`socket_connect`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L912)
	86	+	* [`task_fix_setuid`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L709)
	87	+
34	88		## Prerequisites
35	89
36	90		### kernel capabilities
		skipped 137 lines
174	228		$ rustup component add miri --toolchain nightly
175	229		```
176	230
177		-	## LSM hooks
178		-
179		-	LSM hooks supported by Ebpfguard are:
180		-
181		-	* [`bprm_check_security`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L62)
182		-	* [`file_open`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L620)
183		-	* [`sb_mount`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L128)
184		-	* [`sb_remount`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L147)
185		-	* [`sb_umount`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L159)
186		-	* [`socket_bind`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L904)
187		-	* [`socket_connect`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L912)
188		-	* [`task_fix_setuid`](https://elixir.bootlin.com/linux/v6.2.12/source/include/linux/lsm_hooks.h#L709)
189		-
190		-	## Examples
191		-
192		-	For usage examples check [EXAMPLES.md](EXAMPLES.md).
193		-
194	231		## Get in touch
195	232
196		-	Thank you for using Ebpfguard. Please feel welcome to participate in the [Deepfence community](COMMUNITY.md).
	233	+	Thank you for using Ebpfguard. Please feel welcome to participate in the [Deepfence community](doc/COMMUNITY.md).
197	234
198	235		* [Deepfence Community Website](https://community.deepfence.io)
199	236		* [<img src="https://img.shields.io/badge/[email protected]?logo=slack">](https://join.slack.com/t/deepfence-community/shared_invite/zt-podmzle9-5X~qYx8wMaLt9bGWwkSdgQ) Got a question, need some help? Find the Deepfence team on Slack
		skipped 13 lines

COMMUNITY.md doc/COMMUNITY.md

Content is identical
EXAMPLES.md doc/EXAMPLES.md

Content is identical

■ ■ ■ ■ ■ ■

examples/readme_mount/Cargo.toml

1	+	[package]
2	+	name = "foo"
3	+	version = "0.1.0"
4	+	edition = "2021"
5	+
6	+	# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
7	+
8	+	[dependencies]
9	+	anyhow = { version = "1", features = ["backtrace"] }
10	+	ebpfguard = { path = "../../ebpfguard" }
11	+	env_logger = "0.10"
12	+	log = "0.4"
13	+	tokio = { version = "1.25", features = ["macros", "rt", "rt-multi-thread", "net", "signal", "sync"] }
14	+

■ ■ ■ ■ ■ ■

examples/readme_mount/src/main.rs

1	+	use ebpfguard::{
2	+	policy::{PolicySubject, SbMount},
3	+	PolicyManager,
4	+	};
5	+	use log::info;
6	+
7	+	#[tokio::main]
8	+	async fn main() -> anyhow::Result<()> {
9	+	env_logger::init();
10	+	const BPF_MAPS_PATH: &str = "/sys/fs/bpf/example_sb_mount";
11	+
12	+	// Create a directory where ebpfguard policy manager can store its BPF
13	+	// objects (maps).
14	+	std::fs::create_dir_all(BPF_MAPS_PATH)?;
15	+
16	+	// Create a policy manager.
17	+	let mut policy_manager = PolicyManager::new(BPF_MAPS_PATH)?;
18	+
19	+	// Attach the policy manager to the mount LSM hook.
20	+	let mut sb_mount = policy_manager.attach_sb_mount()?;
21	+
22	+	// Get the receiver end of the alerts channel (for the `file_open` LSM
23	+	// hook).
24	+	let mut sb_mount_rx = sb_mount.alerts().await?;
25	+
26	+	// Define policies which deny mount operations for all processes (except
27	+	// for the specified subject, if defined).
28	+	sb_mount
29	+	.add_policy(SbMount {
30	+	subject: PolicySubject::All,
31	+	allow: false,
32	+	})
33	+	.await?;
34	+
35	+	if let Some(alert) = sb_mount_rx.recv().await {
36	+	info!(
37	+	"sb_mount alert: pid={} subject={}",
38	+	alert.pid, alert.subject
39	+	);
40	+	}
41	+
42	+	Ok(())
43	+	}
44	+

Readme: embedd an example in readme. Move lsm section up