bsdcontrol.rb/README.md

82 lines
1.9 KiB
Markdown
Raw Normal View History

2024-03-01 02:29:43 +01:00
## About
2024-03-01 02:28:22 +01:00
2024-03-08 02:35:34 +01:00
hbsdctl.rb is a C extension that binds libhbsdcontrol from the
[hardenedbsd](https://hardenedbsd.org) project to Ruby. Through
this library, you can query what features are available and if
2024-03-08 05:36:06 +01:00
root: enable, disable or query the status of a feature for a
given file.
2024-03-01 02:28:22 +01:00
2024-03-01 02:29:43 +01:00
## Examples
2024-03-01 02:28:22 +01:00
2024-03-08 05:36:06 +01:00
__Features__
2024-03-01 02:28:22 +01:00
2024-03-10 14:57:39 +01:00
As a regular user account, you can obtain a list of available features:
2024-03-01 02:28:22 +01:00
2024-03-01 02:29:43 +01:00
``` ruby
#!/usr/bin/env ruby
# As a regular user account
2024-03-08 05:36:06 +01:00
require "hbsdctl"
2024-03-01 02:29:43 +01:00
BSD::Control
.available_features
.each do
print "The ", _1.name, " feature is available", "\n"
end
2024-03-01 02:28:22 +01:00
```
2024-03-08 05:36:06 +01:00
__Enable__
2024-03-01 02:28:22 +01:00
2024-03-08 05:36:06 +01:00
As a superuser account, you can enable or disable a feature for a given file.
2024-03-01 02:29:43 +01:00
The example enables the mprotect feature for the emacs binary:
2024-03-01 02:28:22 +01:00
2024-03-01 02:29:43 +01:00
``` ruby
#!/usr/bin/env ruby
2024-03-08 05:36:06 +01:00
# As a superuser account
require "hbsdctl"
2024-03-01 02:29:43 +01:00
BSD::Control
2024-03-08 05:23:16 +01:00
.feature(:mprotect)
2024-03-08 02:35:34 +01:00
.enable!("/usr/local/bin/emacs-29.2")
2024-03-01 02:29:43 +01:00
```
2024-03-01 02:28:22 +01:00
2024-03-08 05:36:06 +01:00
__Status__
As a superuser account, you can query whether or not a feature is enabled or disabled
for a given file. There are four statuses that can be returned: `conflict`, `sysdef`,
`enabled`, and `disabled`. The first status (conflict) is rare and indicates that a
feature is both enabled and disabled. The other three are more common. The `sysdef`
status indicates that a feature takes its settings from the system default (sysctl):
``` ruby
#!/usr/bin/env ruby
# As a superuser account
require "hbsdctl"
BSD::Control
.feature(:mprotect)
.status("/bin/ls") # => :sysdef
```
2024-03-08 02:35:34 +01:00
## Documentation
A complete API reference is available at
[0x1eef.github.io/x/hbsdctl.rb](https://0x1eef.github.io/x/hbsdctl.rb).
2024-03-10 14:57:39 +01:00
## Sources
2024-03-01 02:35:05 +01:00
2024-03-10 14:57:39 +01:00
* [GitHub](https://github.com/0x1eef/hbsdctl.rb)
* [GitLab](https://gitlab.com/0x1eef/hbsdctl.rb)
* [git.hardenedbsd.org](https://git.hardenedbsd.org/0x1eef/hbsdctl.rb)
2024-03-01 02:35:05 +01:00
2024-03-10 14:57:39 +01:00
## Install
2024-03-01 02:35:05 +01:00
**Rubygems.org**
2024-03-01 03:49:37 +01:00
hbsdctl.rb can also be installed via rubygems.org.
2024-03-01 02:35:05 +01:00
gem install hbsdctl.rb
2024-03-01 02:28:22 +01:00
## License
2024-03-01 02:29:43 +01:00
[BSD Zero Clause](https://choosealicense.com/licenses/0bsd/).
<br>
See [LICENSE](./LICENSE).