Skip to content

Commit

Permalink
Update docs (ebuild backend)
Browse files Browse the repository at this point in the history 
Also:
 - properly nest FAQ content
 - fix indentation of code block under notes
 - fix table formatting (at least, as good as GFM tables get)
  • Loading branch information
@Kangie
Kangie committed Dec 19, 2023
1 parent 8383988 commit 3149256
Showing 1 changed file with 112 additions and 97 deletions.
209 changes: 112 additions & 97 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ that are designed to work together. They are copied into /etc/fapolicyd/rules.d/
When the service starts, the systemd service file runs fagenrules which
assembles the units of rules into a comprehensive policy. The policy is
evaluated from top to bottom with the first match winning. You can see the
assembled policy by running
assembled policy by running

```
fapolicyd-cli --list
Expand Down Expand Up @@ -161,7 +161,7 @@ Policy. But you can do that. It is not recommended to do this except when
necessary. Every rule that is added has to potentially be evaluated - which
delays the decision.

If you needed to allow admins access to ping, but deny it to everyone
If you needed to allow admins access to ping, but deny it to everyone
else, you could do that with the following rules:

```
Expand Down Expand Up @@ -224,10 +224,10 @@ The report gives some basic forensic information about what was being accessed.

PERFORMANCE
-----------
When a program opens a file or calls execve, that thread has to wait for
When a program opens a file or calls execve, that thread has to wait for
fapolicyd to make a decision. To make a decision, fapolicyd has to lookup
information about the process and the file being accessed. Each system call
fapolicyd has to make slows down the system.
fapolicyd has to make slows down the system.

To speed things up, fapolicyd caches everything it looks up so that
subsequent access uses the cache rather than looking things up from
Expand Down Expand Up @@ -324,7 +324,7 @@ in the lmdb database is 512 bytes. So, for each 4k page, we can have data on
8 trusted files.

An ideal size for the database is for the statistics to come up around 75% in
case you decide to install new software some day. The formula is
case you decide to install new software some day. The formula is

```
(db_max_size x percentage in use) / desired percentage = new db_max_size
Expand Down Expand Up @@ -419,22 +419,22 @@ to debug the policy is:

Look at the rule that triggered and see if it makes sense that it triggered. If
the rule is a catch all denial, then check if the file is in the trust db. To see the rule that is being triggered, either reproduce the problem with the daemon running in debug-deny mode or change the rules from deny_audit to deny_syslog. If you choose this method, the denials will go into syslog. To see them run:

```
journalctl -b -u fapolicyd.service
```

to list out any events since boot by the fapolicyd service.

Starting with 1.1, fapolicyd-cli includes some diagnostic capabilities.

| Option | What it does |
|------------------------|--------------------------------------------|
| --check-config | Opens fapolicyd.conf and parses it to see if there are any syntax errors in the file. |
| --check-path | Check that every file in $PATH is in the trustdb. (New in 1.1.5) |
| --check-status | Output internal metrics kept by the daemon. (New in 1.1.4) |
| --check-trustdb | Check the trustdb against the files on disk to look for mismatches that will cause problems at run time. |
| --check-watch_fs | Check the mounted file systems against the watch_fs daemon config entry to determine if any file systems need to be added to the configuration. |


| Option | What it does |
| :----------------: | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `--check-config` | Opens fapolicyd.conf and parses it to see if there are any syntax errors in the file. |
| `--check-path` | Check that every file in `$PATH` is in the trustdb. (New in 1.1.5) |
| `--check-status` | Output internal metrics kept by the daemon. (New in 1.1.4) |
| `--check-trustdb` | Check the trustdb against the files on disk to look for mismatches that will cause problems at run time. |
| `--check-watch_fs` | Check the mounted file systems against the watch_fs daemon config entry to determine if any file systems need to be added to the configuration. |

MANAGING TRUST
--------------
Expand Down Expand Up @@ -497,113 +497,129 @@ FAQ
---
1) Can this work with other distributions?

Absolutely! There is a backend API that any trust source has to implement.
This API is located in fapolicyd-backend.h. A new backend needs an init, load,
and destroy function. So, someone who knows the debian package database,
for example, could implement a new backend and send a pull request. We are
looking for collaborators.
Absolutely! There is a backend API that any trust source has to implement.
This API is located in `fapolicyd-backend.h`. A new backend needs an init, load,
and destroy function.

An initial implementation for Debian distributions has been added.
Run:
```
cd deb
./build_deb.sh
```
An initial implementation for Debian distributions has been added, run:

```
cd deb
./build_deb.sh
```

To build the `.deb` package that uses the `debdb` backend.
You must add rules to `/etc/fapolicyd/rules.d/` and change configuration
in `/etc/fapolicyd/fapolicyd.conf` to use `trust=debdb` after installation.

Gentoo-based distributions can try using the ebuild backend:

To build the `.deb` package that uses the `debdb` backend.
You must add rules to `/etc/fapolicyd/rules.d/` and change configuration
in `/etc/fapolicyd/fapolicyd.conf` to use `trust=debdb` after installation.
```
./configure --with-ebuild --with-audit
make -j
make install
```

Also, if the distribution is very small, you can use the file trust database
file. Just add the places where libraries and applications are stored.
To use the ebuild backend:

1. Enable the ebuild backend by adding `trust = ebuilddb` to `/etc/fapolicyd/fapolicyd.conf`
2. Increase `db_max_size` to 100 or more in `/etc/fapolicyd/fapolicyd.conf`
3. Copy the example rules to `/etc/fapolicyd/rules.d/` and run `fagenrules` to compile them.

There is also an ebuild in the Gentoo Repository to simplify installation which
does these things automatically.

Finally, if the distribution is very small (or in an embedded context), consider using
the trust file database - Just whitelist applications or libraries and their hashes.

2) Can SE Linux or AppArmor do this instead?

SE Linux is modeling how an application behaves. It is not concerned about
where the application came from or whether it's known to the system. Basically,
anything in /bin gets bin_t type by default which is not a very restrictive
label. MAC systems serve a different purpose. Fapolicyd by design cares solely
about if this is a known application/library. These are complimentary security
subsystems. There is more information about application whitelisting use cases
at the following NIST website:
SE Linux is modeling how an application behaves. It is not concerned about
where the application came from or whether it's known to the system. Basically,
anything in /bin gets bin_t type by default which is not a very restrictive
label. MAC systems serve a different purpose. Fapolicyd by design cares solely
about if this is a known application/library. These are complimentary security
subsystems. There is more information about application whitelisting use cases
at the following NIST website:

https://www.nist.gov/publications/guide-application-whitelisting
https://www.nist.gov/publications/guide-application-whitelisting

3) Does the daemon check file integrity?

Version 0.9.5 and later supports 3 modes of integrity checking. The first is
based on file size. In this mode, fapolicyd will take the size information
from the trust db and compare it with the measured file size. This test
incurs no overhead since the file size is collected when establishing
uniqueness for caching purposes. It is intended to detect accidental overwrites
as opposed to malicious activity where the attacker can make the file size
match.
Version 0.9.5 and later supports 3 modes of integrity checking. The first is
based on file size. In this mode, fapolicyd will take the size information
from the trust db and compare it with the measured file size. This test
incurs no overhead since the file size is collected when establishing
uniqueness for caching purposes. It is intended to detect accidental overwrites
as opposed to malicious activity where the attacker can make the file size
match.

The second mode is based on using IMA to calculate sha256 hashes and make them
available through extended attributes. This incurs only the overhead of calling
fgetxattr which is fast since there is no path name resolution. The file system
must support i_version. For XFS, this is enabled by default. For other file
systems, this means you need to add the i_version mount option. In either
case, IMA must be setup appropriately.
The second mode is based on using IMA to calculate sha256 hashes and make them
available through extended attributes. This incurs only the overhead of calling
fgetxattr which is fast since there is no path name resolution. The file system
must support i_version. For XFS, this is enabled by default. For other file
systems, this means you need to add the i_version mount option. In either
case, IMA must be setup appropriately.

The third mode is where fapolicyd calculates a SHA256 hash of the file itself
and compares that with what is stored in the trust db.
The third mode is where fapolicyd calculates a SHA256 hash of the file itself
and compares that with what is stored in the trust db.

4) This is only looking at location. Can't this be defeated by simply moving
the files to another location?

Yes, this is checking to see if this is a known file. Known files have a known
location. The shipped policy prevents execution from /tmp, /var/tmp, and $HOME
based on the fact that no rpm package puts anything there. Also, moving a file
means it's no longer "known" and will be blocked from executing. And if
something were moved to overwrite it, then the hash is no longer the same and
that will make it no longer trusted.
Yes, this is checking to see if this is a known file. Known files have a known
location. The shipped policy prevents execution from /tmp, /var/tmp, and $HOME
based on the fact that no rpm package puts anything there. Also, moving a file
means it's no longer "known" and will be blocked from executing. And if
something were moved to overwrite it, then the hash is no longer the same and
that will make it no longer trusted.

5) Does this protect against root modifications?

If you are root, you can change the fapolicyd rules or simply turn off the
daemon. So, this is not designed to prevent root from doing things. None of
the integrity subsystems on Linux are designed to prevent root from doing
things. There has to be a way of doing updates or disabling something for
troubleshooting. For example, you can change IMA to ima_appraise=fix in
/etc/default/grub. You can run setenforce=0 to turn off selinux. You can also
set selinux=0 for the boot prompt. The IPE integrity subsystem can be turned
off via
If you are root, you can change the fapolicyd rules or simply turn off the
daemon. So, this is not designed to prevent root from doing things. None of
the integrity subsystems on Linux are designed to prevent root from doing
things. There has to be a way of doing updates or disabling something for
troubleshooting. For example, you can change IMA to ima_appraise=fix in
/etc/default/grub. You can run setenforce=0 to turn off selinux. You can also
set selinux=0 for the boot prompt. The IPE integrity subsystem can be turned
off via

```
echo -n 0 > "/sys/kernel/security/ipe/Ex Policy/active"
```
```
echo -n 0 > "/sys/kernel/security/ipe/Ex Policy/active"
```

and so on. Since they can all be disabled, the fact that an admin can issue a
service stop command is not a unique weakness.
and so on. Since they can all be disabled, the fact that an admin can issue a
service stop command is not a unique weakness.

6) How do you prevent race conditions on startup? Can something execute before
the daemon takes control?

One of the design goals is to take control before users can login. Users are
the main problem being addressed. They can pip install apps to the home dir
or do other things an admin may wish to prevent. Only root can install things
that run before login. And again, root can change the rules or turn off the
daemon.
One of the design goals is to take control before users can login. Users are
the main problem being addressed. They can pip install apps to the home dir
or do other things an admin may wish to prevent. Only root can install things
that run before login. And again, root can change the rules or turn off the
daemon.

Another design goal is to prevent malicious apps from running. Suppose someone
guesses your password and they login to your account. Perhaps they wish to
ransomware your home dir. The app they try to run is not known to the system
and will be stopped. Or suppose there is an exploitable service on your system.
The attacker is lucky enough to pop a shell. Now they want to download
privilege escalation tools or perhaps an LD_PRELOAD key logger. Since neither
of these are in the trust database, they won't be allowed to run.
Another design goal is to prevent malicious apps from running. Suppose someone
guesses your password and they login to your account. Perhaps they wish to
ransomware your home dir. The app they try to run is not known to the system
and will be stopped. Or suppose there is an exploitable service on your system.
The attacker is lucky enough to pop a shell. Now they want to download
privilege escalation tools or perhaps an LD_PRELOAD key logger. Since neither
of these are in the trust database, they won't be allowed to run.

This is really about stopping escalation or exploitation before the attacker
can gain any advantage to install root kits. If we can do that, UEFI secure
boot can make sure no other problems exist during boot.
This is really about stopping escalation or exploitation before the attacker
can gain any advantage to install root kits. If we can do that, UEFI secure
boot can make sure no other problems exist during boot.

Wrt to the second question being asked, fapolicyd starts very early in the
boot process and startup is very fast. It's running well before other login
daemons.
Wrt to the second question being asked, fapolicyd starts very early in the
boot process and startup is very fast. It's running well before other login
daemons.

NOTES
-----

* It's highly recommended to run in permissive mode while you are testing the
daemon's policy.

Expand All @@ -624,12 +640,11 @@ file content modifications can occur.
* If for some reason rpm database errors are detected, you may need to do
the following:

```
1. db_verify /var/lib/rpm/Packages
if OK, then
2. rm -f /var/lib/rpm/__db*
3. rpm --rebuilddb
```
```
1. db_verify /var/lib/rpm/Packages
if OK, then
2. rm -f /var/lib/rpm/__db*
3. rpm --rebuilddb
```

[1] - https://git.kernel.org/pub/scm/linux/kernel/git/jack/linux-fs.git/commit/?id=66917a3130f218dcef9eeab4fd11a71cd00cd7c9

0 comments on commit 3149256

Please sign in to comment.