Report that --print and --generate can't be used together

[kconfig-hardened-check.git] / README.md

diff --git a/README.md b/README.md
index 919654006c5b15cffad92e5cf0e3a59a194c70fe..714bb4af1431f2d5c8bb93d674ad1643b0bf5918 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,8 +1,10 @@
 # kconfig-hardened-check
 
 # kconfig-hardened-check
 

-![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/a13xp0p0v/kconfig-hardened-check?label=release)
-![functional test](https://github.com/a13xp0p0v/kconfig-hardened-check/workflows/functional%20test/badge.svg)
-[![Coverage Status](https://codecov.io/gh/a13xp0p0v/kconfig-hardened-check/graph/badge.svg)](https://codecov.io/gh/a13xp0p0v/kconfig-hardened-check)
+[![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/a13xp0p0v/kconfig-hardened-check?label=release)](https://github.com/a13xp0p0v/kconfig-hardened-check/tags)<br />
+[![functional test](https://github.com/a13xp0p0v/kconfig-hardened-check/workflows/functional%20test/badge.svg)](https://github.com/a13xp0p0v/kconfig-hardened-check/actions/workflows/functional_test.yml)
+[![functional test coverage](https://codecov.io/gh/a13xp0p0v/kconfig-hardened-check/graph/badge.svg?flag=functional_test)](https://codecov.io/gh/a13xp0p0v/kconfig-hardened-check)<br />
+[![engine unit-test](https://github.com/a13xp0p0v/kconfig-hardened-check/workflows/engine%20unit-test/badge.svg)](https://github.com/a13xp0p0v/kconfig-hardened-check/actions/workflows/engine_unit-test.yml)
+[![unit-test coverage](https://codecov.io/gh/a13xp0p0v/kconfig-hardened-check/graph/badge.svg?flag=engine_unit-test)](https://codecov.io/gh/a13xp0p0v/kconfig-hardened-check)

 
 ## Motivation
 
 
 ## Motivation
 


@@ -12,8 +14,8 @@ make our systems more secure.
 
 But nobody likes checking configs manually. So let the computers do their job!
 
 
 But nobody likes checking configs manually. So let the computers do their job!
 

-__kconfig-hardened-check__ helps me to check the Linux kernel options
-against my security hardening preferences, which are based on the
+__kconfig-hardened-check__ is a tool for checking the security hardening options of the Linux kernel.
+The recommendations are based on

 
   - [KSPP recommended settings][1]
   - [CLIP OS kernel configuration][2]
 
   - [KSPP recommended settings][1]
   - [CLIP OS kernel configuration][2]


@@ -32,10 +34,11 @@ and functionality of userspace software. So for choosing these parameters consid
 the threat model of your Linux-based information system and perform thorough testing
 of its typical workload.
 
 the threat model of your Linux-based information system and perform thorough testing
 of its typical workload.
 

-## Repository mirrors
+## Repositories

 
 

- - At Codeberg: [https://codeberg.org/a13xp0p0v/kconfig-hardened-check](https://codeberg.org/a13xp0p0v/kconfig-hardened-check)
- - At GitFlic: [https://gitflic.ru/project/a13xp0p0v/kconfig-hardened-check](https://gitflic.ru/project/a13xp0p0v/kconfig-hardened-check)
+ - Main at GitHub <https://github.com/a13xp0p0v/kconfig-hardened-check>
+ - Mirror at Codeberg: <https://codeberg.org/a13xp0p0v/kconfig-hardened-check>
+ - Mirror at GitFlic: <https://gitflic.ru/project/a13xp0p0v/kconfig-hardened-check>

 
 ## Supported microarchitectures
 
 
 ## Supported microarchitectures
 


@@ -60,24 +63,29 @@ Some Linux distributions also provide `kconfig-hardened-check` as a package.
 
 ## Usage
 ```
 
 ## Usage
 ```

-usage: kconfig-hardened-check [-h] [--version] [-p {X86_64,X86_32,ARM64,ARM}]
-                              [-c CONFIG]
-                              [-l CMDLINE]
-                              [-m {verbose,json,show_ok,show_fail}]
+usage: kconfig-hardened-check [-h] [--version] [-m {verbose,json,show_ok,show_fail}]
+                              [-c CONFIG] [-l CMDLINE] [-p {X86_64,X86_32,ARM64,ARM}]
+                              [-g {X86_64,X86_32,ARM64,ARM}]

 
 A tool for checking the security hardening options of the Linux kernel
 
 
 A tool for checking the security hardening options of the Linux kernel
 

-optional arguments:
+options:

   -h, --help            show this help message and exit
   --version             show program's version number and exit
   -h, --help            show this help message and exit
   --version             show program's version number and exit

-  -p {X86_64,X86_32,ARM64,ARM}, --print {X86_64,X86_32,ARM64,ARM}
-                        print security hardening preferences for the selected architecture
-  -c CONFIG, --config CONFIG
-                        check the kernel kconfig file against these preferences
-  -l CMDLINE, --cmdline CMDLINE
-                        check the kernel cmdline file against these preferences

   -m {verbose,json,show_ok,show_fail}, --mode {verbose,json,show_ok,show_fail}
                         choose the report mode
   -m {verbose,json,show_ok,show_fail}, --mode {verbose,json,show_ok,show_fail}
                         choose the report mode

+  -c CONFIG, --config CONFIG
+                        check the security hardening options in the kernel Kconfig file
+                        (also supports *.gz files)
+  -l CMDLINE, --cmdline CMDLINE
+                        check the security hardening options in the kernel cmdline file
+                        (contents of /proc/cmdline)
+  -p {X86_64,X86_32,ARM64,ARM}, --print {X86_64,X86_32,ARM64,ARM}
+                        print the security hardening recommendations for the selected
+                        microarchitecture
+  -g {X86_64,X86_32,ARM64,ARM}, --generate {X86_64,X86_32,ARM64,ARM}
+                        generate a Kconfig fragment with the security hardening options
+                        for the selected microarchitecture

 ```
 
 ## Output modes
 ```
 
 ## Output modes


@@ -335,14 +343,22 @@ sysrq_always_enabled                    |cmdline| is not set |    my    |cut_att
 [+] Config check is finished: 'OK' - 122 / 'FAIL' - 101
 ```
 
 [+] Config check is finished: 'OK' - 122 / 'FAIL' - 101
 ```
 

-## kconfig-hardened-check versioning
-
-I usually update the kernel security hardening recommendations every few kernel releases.
-
-So the version of `kconfig-hardened-check` is associated with the corresponding version of the kernel.
+## Generating a Kconfig fragment with the security hardening options

 
 

-The version format is: __[major_number].[kernel_version].[kernel_patchlevel]__
+With the `-g` argument, the tool generates a Kconfig fragment with the security hardening options for the selected microarchitecture.

 
 

+This Kconfig fragment can be merged with the existing Linux kernel config:
+```
+$ ./bin/kconfig-hardened-check -g X86_64 > /tmp/fragment
+$ cd ~/linux-src/
+$ ./scripts/kconfig/merge_config.sh .config /tmp/fragment
+Using .config as base
+Merging /tmp/fragment
+Value of CONFIG_BUG_ON_DATA_CORRUPTION is redefined by fragment /tmp/fragment:
+Previous value: # CONFIG_BUG_ON_DATA_CORRUPTION is not set
+New value: CONFIG_BUG_ON_DATA_CORRUPTION=y
+ ...
+```

 
 ## Questions and answers
 
 
 ## Questions and answers