--ids-check/--ids-init documentation

2 files changed, 135 insertions, 25 deletions

diff --git a/README.md b/README.md
index 9dd9bbbfd..a856495f0 100644
--- a/README.md
+++ b/README.md
@@ -183,34 +183,65 @@ in order to give users a chance to switch their local profiles.
 The latest discussion on this issue is here: https://github.com/netblue30/firejail/issues/4379
 
 ### Intrusion Detection System ###
-
-We are adding IDS capabilities in the next release. We have the list of files in [/etc/firejail/ids.config](https://github.com/netblue30/firejail/blob/master/etc/ids.config),
-and we generate a [BLAKE2](https://en.wikipedia.org/wiki/BLAKE_%28hash_function%29) checksum in /var/lib/firejail/username.ids.
-The program runs as regular user, each user has his own file in /var/lib/firejail.
-
-Initialize the database:
-`````
-$ firejail --ids-init
-Loading /etc/firejail/ids.config config file
-500 1000 1500 2000
-2457 files scanned
-IDS database initialized
 `````
+      --ids-check
+              Check  file  hashes previously generated by --ids-check. See IN‐
+              TRUSION DETECTION SYSTEM section for more details.
+
+              Example:
+              $ firejail --ids-check
+
+       --ids-init
+              Initialize file hashes. See INTRUSION DETECTION  SYSTEM  section
+              for more details.
+
+              Example:
+              $ firejail --ids-init
+
+INTRUSION DETECTION SYSTEM (IDS)
+       The  host-based  intrusion detection system tracks down and audits user
+       and  system  file  modifications.   The  feature  is  configured  using
+       /etc/firejail/ids.config    file,   the   checksums   are   stored   in
+       /var/lib/firejail/USERNAME.ids, where USERNAME is the name of the  cur‐
+       rent user. We use BLAKE2 cryptographic function for hashing.
+
+       As a regular user, initialize the database:
+
+       $ firejail --ids-init
+       Opening config file /etc/firejail/ids.config
+       Loading config file /etc/firejail/ids.config
+       Opening config file /etc/firejail/ids.config.local
+       500 1000 1500 2000
+       2466 files scanned
+       IDS database initialized
+
+       The  default configuration targets several system executables in direc‐
+       tories such as /bin, /sbin, /usr/bin, /usr/sbin, and  several  critical
+       config  files in user home directory such as ~/.bashrc, ~/.xinitrc, and
+       ~/.config/autostart. Several system config files in /etc directory  are
+       also hashed.
+
+       Run --ids-check to audit the system:
+
+       $ firejail --ids-check
+       Opening config file /etc/firejail/ids.config
+       Loading config file /etc/firejail/ids.config
+       Opening config file /etc/firejail/ids.config.local
+       500 1000 1500
+       Warning: modified /home/netblue/.bashrc
+       2000
+       2466 files scanned: modified 1, permissions 0, new 0, removed 0
+
+       The  program  will  print  the  files that have been modified since the
+       database was created, or the files with different  access  permissions.
+       New files and deleted files are also flagged.
+
+       Currently  while  scanning  the file system symbolic links are not fol‐
+       lowed, and files the user doesn't have  read  access  to  are  silently
+       dropped.   The  program  can  also be run as root (sudo firejail --ids-
+       init/--ids-check).
 
-Later, we check it:
 `````
-$ firejail --ids-check
-Loading /etc/firejail/ids.config config file
-500 1000 1500
-Warning: modified /home/netblue/.bashrc
-2000
-2457 files scanned: modified 1, permissions 0, new 0, removed 0
-`````
-The program will print the files that have been modified since the database was created, or the files with different access permissions.
-New files and deleted files are also flagged.
-
-Currently while scanning the file system symbolic links are not followed, and files the user doesn't have read access to are silently dropped.
-The program can also be run as root (sudo firejail --ids-init/--ids-check).
 
 ### Deteministic Shutdown
 `````
diff --git a/src/man/firejail.txt b/src/man/firejail.txt
index 499339264..b5cb1e7c2 100644
--- a/src/man/firejail.txt
+++ b/src/man/firejail.txt
@@ -821,6 +821,26 @@ Example:
 $ firejail \-\-hosts-file=~/myhosts firefox
 
 .TP
+\fB\-\-ids-check
+Check file hashes previously generated by \-\-ids-check. See INTRUSION DETECTION SYSTEM section for more details.
+.br
+
+.br
+Example:
+.br
+$ firejail \-\-ids-check
+
+.TP
+\fB\-\-ids-init
+Initialize file hashes. See INTRUSION DETECTION SYSTEM section for more details.
+.br
+
+.br
+Example:
+.br
+$ firejail \-\-ids-init
+
+.TP
 \fB\-\-ignore=command
 Ignore command in profile file.
 .br
@@ -3208,6 +3228,65 @@ $ firejail \-\-put=mybrowser xpra-clipboard.png ~/Downloads/xpra-clipboard.png
 $ firejail \-\-cat=mybrowser ~/.bashrc
 .br
 #endif
+
+.SH INTRUSION DETECTION SYSTEM (IDS)
+The host-based intrusion detection system tracks down and audits user and system file modifications.
+The feature is configured using /etc/firejail/ids.config file, the checksums are stored in /var/lib/firejail/USERNAME.ids,
+where USERNAME is the name of the current user. We use BLAKE2 cryptographic function for hashing.
+
+As a regular user, initialize the database:
+.br
+
+.br
+$ firejail --ids-init
+.br
+Opening config file /etc/firejail/ids.config
+.br
+Loading config file /etc/firejail/ids.config
+.br
+Opening config file /etc/firejail/ids.config.local
+.br
+500 1000 1500 2000
+.br
+2466 files scanned
+.br
+IDS database initialized
+.br
+
+.br
+The default configuration targets several system executables in directories such as /bin, /sbin, /usr/bin, /usr/sbin, and several critical config files in user home directory
+such as ~/.bashrc, ~/.xinitrc, and ~/.config/autostart. Several system config files in /etc directory are also hashed.
+.br
+
+.br
+Run --ids-check to audit the system:
+.br
+
+.br
+$ firejail --ids-check
+.br
+Opening config file /etc/firejail/ids.config
+.br
+Loading config file /etc/firejail/ids.config
+.br
+Opening config file /etc/firejail/ids.config.local
+.br
+500 1000 1500
+.br
+Warning: modified /home/netblue/.bashrc
+.br
+2000
+.br
+2466 files scanned: modified 1, permissions 0, new 0, removed 0
+.br
+
+.br
+The program will print the files that have been modified since the database was created, or the files with different access permissions.
+New files and deleted files are also flagged.
+
+Currently while scanning the file system, symbolic links are not followed, and files the user doesn't have read access to are silently dropped.
+The program can also be run as root (sudo firejail --ids-init/--ids-check).
+
 .SH MONITORING
 Option \-\-list prints a list of all sandboxes. The format
 for each process entry is as follows: