Set config.json to 644 permissions; add note about user permissions to README.md; add advanced example with Dockerfile

Author: xenago

Cargo.toml

@@ -33,7 +33,7 @@ priority = "optional"
 extended-description = "A plugin for the Name Service Switch (NSS) framework that parses the output of commands to resolve queries."
 assets = [
     ["target/release/libnss_shim.so", "lib/libnss_shim.so.2", "644"],
-    ["default_config/config.json", "etc/libnss_shim/config.json", "640"],
+    ["default_config/config.json", "etc/libnss_shim/config.json", "644"],
     ["README.md", "usr/share/doc/libnss_shim/README", "644"],
 ]
 conf-files = ["etc/libnss_shim/config.json"]
@@ -43,7 +43,7 @@ maintainer-scripts = "debian"
 summary = "A plugin for the Name Service Switch (NSS) framework that parses the output of commands to resolve queries."
 assets = [
     { source = "target/release/libnss_shim.so", dest = "/lib64/libnss_shim.so.2", mode = "644", config = false, doc = false, user = "root", group = "root" },
-    { source = "default_config/config.json", dest = "/etc/libnss_shim/config.json", mode = "640", config = true, doc = false, user = "root", group = "root" },
+    { source = "default_config/config.json", dest = "/etc/libnss_shim/config.json", mode = "644", config = true, doc = false, user = "root", group = "root" },
     { source = "README.md", dest = "/usr/share/doc/libnss_shim/README", mode = "644", config = false, doc = true, user = "root", group = "root" },
 ]
 post_install_script = "debian/postinst"

README.md

@@ -103,22 +103,24 @@ to be used with NSS.
 
 6. Perform NSS queries to validate the installation, for example using the built-in `getent` tool.
 
-   Some sample commands to test your implementation:
+    Some sample commands to test your implementation:
     ```
     getent group
     getent passwd
     getent shadow
     getent group <groupname>
     ```
-   A very basic test config is available that will respond to `getent group` calls with a fake group (see the demo GIF
-   at the top of this file):
-
-       curl -sLo /etc/libnss_shim/config.json https://raw.githubusercontent.com/xenago/libnss_shim/main/default_config/sample_custom_config.json
+    A very basic test config is available that will respond to `getent group` calls with a fake group (see the demo GIF
+    at the top of this file):
+    
+       curl -sLo /etc/libnss_shim/config.json https://raw.githubusercontent.com/xenago/libnss_shim/main/samples/basic/custom_config.json
        getent group | tail -1
-
-   If the installation worked, the output should look like:
-
-       testgroup::1008:fake-username,another-user
+    
+    If the installation worked, the output should look like:
+    
+       test-shim-group::1008:fake-username,another-user
+    
+    A more complex configuration example can be found at [`samples/advanced`](samples/advanced), with a `Dockerfile`.
 
 ## Uninstall
 
@@ -163,7 +165,7 @@ commands run by `libnss_shim`:
 - `<$uid>`
 
 Using only that information, here is the
-[extremely basic test example of `config.json`](default_config/sample_custom_config.json) - one database is defined,
+[extremely basic test example of `config.json`](samples/basic/custom_config.json) - one database is defined,
 `group`, with just a single function, `get_all_entries`:
 
 ```
@@ -172,7 +174,7 @@ Using only that information, here is the
     "group": {
       "functions": {
         "get_all_entries": {
-          "command": "echo 'testgroup::1008:fake-username,another-user'"
+          "command": "echo 'test-shim-group::1008:fake-username,another-user'"
         }
       }
     }
@@ -181,7 +183,7 @@ Using only that information, here is the
 ```
 
 The command defined for `get_all_entries` prints out a single line to `stdout`, describing a fake group
-called `testgroup` with `gid=1008` and two members. That output is then captured by `libss_shim` and returned
+called `test-shim-group` with `gid=1008` and two members. That output is then captured by `libss_shim` and returned
 to `NSS` whenever a call is made requesting all the group entries (e.g. `getent group`).
 
 To support command execution, the following options can be set globally and overridden for specific databases and/or
@@ -359,9 +361,16 @@ and `usize` are platform-dependent and can be 32 or 64-bits):
 
 ## Security
 
-This NSS plugin runs commands defined in the file `/etc/libnss_shim/config.json`, which is only accessible to `root` by
-default. Ensure that this file, the commands defined inside it, and any other related resources remain inaccessible to
-other users, or the system may be vulnerable to privilege escalation attacks.
+This NSS plugin runs commands defined in the file `/etc/libnss_shim/config.json`, which is only writable by the `root` 
+user by default. Ensure that this file, the commands defined inside it, and any other related resources remain read-only
+to other users, or the system may be vulnerable to privilege escalation attacks.
+
+To enable non-root users to access resources defined by `libnss_shim`, they must be able to access the commands defined
+in `config.json`. For example, if a file `script.py` is being used, it will need to be readable (along with the Python 
+interpreter used to run it):
+
+    sudo chown root:root /path/to/custom/script.py
+    sudo chmod 644 /path/to/custom/script.py
 
 It is recommended to pass data (like `<$name>`) using environment variables rather than arguments, except for
 testing purposes. Environment variables are generally private, whereas commands/launch args are not.

samples/advanced/Dockerfile

@@ -0,0 +1,17 @@
+# EL distro example
+FROM docker.io/almalinux:9
+
+# Install Python to run the `custom-resolver.py` script
+RUN yum install -y python3
+
+# Install latest release of libnss_shim available for this architecture
+RUN curl -s https://api.github.com/repos/xenago/libnss_shim/releases/latest | grep "browser_download_url.*.$(uname -m)" | cut -d : -f 2,3 | tr -d \" | tr -d " " | xargs -n 1 curl -sLO
+RUN rpm -Ui libnss_shim*.rpm
+RUN rm libnss_shim*.rpm
+
+# Import config and scripts
+COPY custom_config.json /etc/libnss_shim/config.json
+COPY custom-resolver.py /etc/libnss_shim/resolver.py
+
+# Run bash by default
+ENTRYPOINT ["/bin/bash"]

samples/advanced/custom-resolver.py

@@ -0,0 +1,64 @@
+import os
+import sys
+
+# Expected syntax example: `resolver.py --group --all`
+# The database is `--group` and the function is `--all`
+db = sys.argv[1]
+fn = sys.argv[2]
+
+group_entries = {
+    "test-shim-users": "test-shim-users:x:2000:test-shim-user-1,test-shim-user-2,test-shim-user-3",
+    "test-shim-user-1": "test-shim-user-1:x:2001:",
+    "test-shim-user-2": "test-shim-user-2:x:2002:",
+    "test-shim-user-3": "test-shim-user-3:x:2003:"
+}
+
+passwd_entries = {
+    "test-shim-user-1": "test-shim-user-1:x:2001:2001::/home/test-shim-user-1:/bin/bash",
+    "test-shim-user-2": "test-shim-user-2:x:2002:2002::/home/test-shim-user-1:/bin/bash",
+    "test-shim-user-3": "test-shim-user-3:x:2003:2003::/home/test-shim-user-1:/bin/bash"
+}
+
+# Each test user's password is the same as its username
+shadow_entries = {
+    "test-shim-user-1": "test-shim-user-1:$y$j9T$mpqMRQPh51zsMQlg6Koa5/$iYcT2urasxmk99rWCuahIEcNEQDGZcVN0876t80XUm2:19879:0:99999:7:::",
+    "test-shim-user-2": "test-shim-user-2:$y$j9T$SEsXgfv/SUN3EZQJqLfIA/$mG9uKqlqDOqY2oYzuu1O89nmf1BiYs2//3rPof97vq9:19879:0:99999:7:::",
+    "test-shim-user-3": "test-shim-user-3:$y$j9T$loMKkB7paRkhAPE7VUa9I.$7CoM0O7XZASdb4olZ8w3YkyjMw2TpoBjlUynOXDLOEB:19879:0:99999:7:::"
+}
+
+if db == "--group":
+    if fn == "--all":
+        for entry in group_entries.values():
+            print(entry)
+    elif fn == "--name":
+        provided_name = os.getenv("LIBNSS_SHIM_GROUP_NAME", default = None)
+        if provided_name is not None and provided_name in group_entries:
+            print(group_entries[provided_name])
+    elif fn == "--id":
+        provided_gid = os.getenv("LIBNSS_SHIM_GROUP_ID", default = None)
+        if provided_gid is not None:
+            for group in group_entries.values():
+                if group.split(":")[2] == provided_gid:
+                    print(group)
+elif db == "--passwd":
+    if fn == "--all":
+        for entry in passwd_entries.values():
+            print(entry)
+    elif fn == "--name":
+        provided_name = os.getenv("LIBNSS_SHIM_PASSWD_NAME", default = None)
+        if provided_name is not None and provided_name in passwd_entries:
+            print(passwd_entries[provided_name])
+    elif fn == "--id":
+        provided_uid = os.getenv("LIBNSS_SHIM_PASSWD_ID", default = None)
+        if provided_uid is not None:
+            for user_entry in passwd_entries.values():
+                if user_entry.split(":")[2] == provided_uid:
+                    print(user_entry)
+elif db == "--shadow":
+    if fn == "--all":
+        for entry in shadow_entries.values():
+            print(entry)
+    elif fn == "--name":
+        provided_name = os.getenv("LIBNSS_SHIM_SHADOW_NAME", default = None)
+        if provided_name is not None and provided_name in shadow_entries:
+            print(shadow_entries[provided_name])

samples/advanced/custom_config.json

@@ -0,0 +1,56 @@
+{
+  "databases": {
+    "group": {
+      "functions": {
+        "get_all_entries": {
+          "command": "python3 /etc/libnss_shim/resolver.py --group --all"
+        },
+        "get_entry_by_gid": {
+          "command": "python3 /etc/libnss_shim/resolver.py --group --id",
+          "env": {
+            "LIBNSS_SHIM_GROUP_ID": "<$gid>"
+          }
+        },
+        "get_entry_by_name": {
+          "command": "python3 /etc/libnss_shim/resolver.py --group --name",
+          "env": {
+            "LIBNSS_SHIM_GROUP_NAME": "<$name>"
+          }
+        }
+      }
+    },
+    "passwd": {
+      "functions": {
+        "get_all_entries": {
+          "command": "python3 /etc/libnss_shim/resolver.py --passwd --all"
+        },
+        "get_entry_by_uid": {
+          "command": "python3 /etc/libnss_shim/resolver.py --passwd --id",
+          "env": {
+            "LIBNSS_SHIM_PASSWD_ID": "<$uid>"
+          }
+        },
+        "get_entry_by_name": {
+          "command": "python3 /etc/libnss_shim/resolver.py --passwd --name",
+          "env": {
+            "LIBNSS_SHIM_PASSWD_NAME": "<$name>"
+          }
+        }
+      }
+    },
+    "shadow": {
+      "functions": {
+        "get_all_entries": {
+          "command": "python3 /etc/libnss_shim/resolver.py --shadow --all"
+        },
+        "get_entry_by_name": {
+          "command": "python3 /etc/libnss_shim/resolver.py --shadow --name",
+          "env": {
+            "LIBNSS_SHIM_SHADOW_NAME": "<$name>"
+          }
+        }
+      }
+    }
+  },
+  "debug" : false
+}

default_config/sample_custom_config.json samples/basic/custom_config.json

@@ -3,7 +3,7 @@
     "group": {
       "functions": {
         "get_all_entries": {
-          "command": "echo 'testgroup::1008:fake-username,another-user'"
+          "command": "echo 'test-shim-group::1008:fake-username,another-user'"
         }
       }
     }