A linux PAM module that provides access control by ip, mac-address, or country-code/region.
C Other Shell Makefile M4
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
LICENCE Initial commit May 20, 2015
Makefile.in
README.md
common.h
configure
configure.ac
install-sh
pam_ihosts.8
pam_module.c
utility.c
utility.h

README.md

#PAM IHOSTS

This is a PAM (Pluggable Authentication Modules) that only allows login from certain hosts, either based on mac-address, ip-address, or their region looked as up in internet registrar stats files. pam_ihosts is not an authentication module, it's an account module.This means that it comes into play only after a user has already authenticated, and provides extra checks as to whether an authenticated user should be alowed to log in. This allows fine-grained control of which hosts a user is allowed to login from, with external logins being controlled by region and ip, and internal networks being controlled by mac-address or ip, the former allowing control even in DHCP environments.

As of version 1.2 both IP4 and IP6 are supported.

#BIG FAT WARNING

Firstly, you should be aware that changing your PAM configuration could result in locking yourself out of your own computer systems if you get something wrong or encounter some kind of weird error.

This PAM module is free software under the Gnu Public Licence version 3, and comes with no express or implied warranties or guarentees of anything.

By default pam_ihosts.so denies login. Options must be supplied to specify the ip-addresss, mac-address, regions or country-codes of those hosts that are allowed to login.

INSTALL

The usual proceedure:

./configure
make
make install

should work. The 'make install' stage will have to be done as root. This will copy the pam_ihosts.so file into /lib/security.

CONFIGURATION

pam_ihosts.so is configured by adding a line to the appropriate file in /etc/pam.d. So, for example, if we wish to add pam_ihosts to the 'sshd' service, we would add the following line to /etc/pam.d/sshd

auth    required  pam_ihosts.so user=root file=/etc/10k-common-passwords.txt

This specifies that, for user root, we should check for ihosts in the file /etc/10k-common-passwords.txt, which is a cleartext list of commonly used passwords.

The config only relates to the specified user. Other users will log in as normal. To make a configuration relate to all users, use the '*' wildcard.

Configuration options are:

user=[user patterns]
Comma separated list of fnmatch (shell-style) patterns that identify users for whom this rule applies. To match all users either leave this out, leave it blank, or explicitly set it to 'user=*'. A '!' character at the start of the pattern allows inversion, so to match all users but root use: 'user=!root'

syslog
Record events via syslog messages

script=[path]
Run script in the event of a DENY. Arguments passed to the script will be 'User', 'IP', 'Mac Address' and 'Region'. 'Region' will be in the format <registrar>:<countrycode>, so for example, ripencc:GB.

allow-ip=[ip]
allow-ips=[ip]
A comma-separated list of fnmatch patterns that match IP addresses allowed to log in.

allow-mac=[mac]
allow-macs=[mac]
A comma-separated list of fnmatch patterns that match MAC addresses allowed to log in.

allow-dev=[dev]
allow-devs=[dev]
allow-device=[dev]
allow-devices=[dev]
A comma-separated list of fnmatch patterns that match network device names that the connection is coming to. This is the network adapter on your machine that is receiving the connection from the remote host.

allow-region=[region]
allow-regions=[region]
A comma-separated list of fnmatch patterns that match region strings looked up in IP registrar files. Region strings are in the format <registrar>:<countrycode>. This option requires you to supply the paths to the region files with the 'region-files' option. For more details see 'REGIONS' below.

region-files=[path]
A comma-separated list of paths to files containing IP registrar assignments. For more details see 'REGIONS' below.

blacklist=[paths] A comma-separated list of paths to files containing IP addresses, MAC addresses or hostnames that are \fBblacklisted\fP (denied login). The files must contain one item (ip address) per line. Each path can be prefixed with "mmap:" in which case the program will use a shared mmap of the file (see MMAPPED FILES below).

whitelist=[paths] A comma-separated list of paths to files containing IP addresses, MAC addresses or hostnames that are \fBwhitelisted\fP (allowed login). The files must contain one item (ip address) per line. Each path can be prefixed with "mmap:" in which case the program will use a shared mmap of the file (see MMAPPED FILES below).

dnsblacklist=[domains] A comma-separated list of domains to use in dns-blacklist lookups. So, for instance "dnsblacklist=zen.spamhaus.org,bots.abuse.net" would check if the host was present in zen.spamhaus.org or bots.abuse.net dns blacklists. Items for which a matching entry is returned are DENIED login. DNS lookups are not executed in parallel but one after the other, so unfortunately login can become slow if many lists are queried.

dnswhitelist=[domains] A comma-separated list of domains to use in dns-whitelist lookups. So, for instance "dnswhitelist=whitelist.spamhaus.org,mylist.local" would check if the host was present in whitelist.spamhaus.org or mylist.local. Items for which a matching entry is returned are ALLOWED login. DNS lookups are not executed in parallel but one after the other, so unfortunately login can become slow if many lists are queried.

MAC address and device matches

pam_ihosts.so looks up MAC addresses and devices in the /proc/net/arps file. If an IP does not have an entry in this file, then both MAC address and Device will be set to 'remote', as the connecting host is not on the same subnet as the target host.

REGIONS

Region information is looked up in files provided by the Regional Internet Registries. These files are downloadable at the following addresses:

http://ftp.lacnic.net/pub/stats/lacnic/delegated-lacnic-latest # Latin America http://ftp.ripe.net/ripe/stats/delegated-ripencc-latest # Europe, Russia, Middle East http://ftp.arin.net/pub/stats/arin/delegated-arin-extended-latest # North America http://ftp.afrinic.net/pub/stats/afrinic/delegated-afrinic-latest # Africa http://ftp.apnic.net/stats/apnic/delegated-apnic-latest # Asia Pacific

These files contain information about ip-address assignments against country-code. pam_ihosts looks an ip-address up in them, and extracts a string in the form <registrar>:<countrycode>, against which it matches the 'allow-region' option.

A special case are 'private' IP addresses (e.g. 10.x.x.x, 192.168.x.x). These will return the string 'local'.

BLACKLISTS/WHITELISTS

Blacklist/whitelist files contain IP addresses, hostnames, or MAC addresses that are either denied or allowed login. One item per line. All three types of item can be present in the same file. Blacklist files are checked first, and then can be overridden with whitelist files. As pam_ihosts denies login by default, so a whitelist file can be used on its own. To use only a blacklist file, one would have to specify "allow-ip=*" and then specify a blacklist file, which would have the effect of allowing everything except those things in the blacklist file.

MMAPPED FILES

Blacklist, whitelist and region file paths can be prefixed with "mmap:" In this case pam_ihosts uses a shared memory mapping of the file. Provided that some other program currently has the file mapped, pam_ihosts will not have to load the file from disk, as it will already be available as shared memory. This can significantly improve performance for large files, at the cost of some memory. If no other program has the file mmapped, then pam_ihosts loads it into shared memory, but has to pay the performance cost of loading it from disk. Therefore, for this system to deliver a benefit, some long-lived program has to keep the files mapped.

ENVIRONMENT VARIABLES

On login pam_ihosts stores the source IP address in IHOSTS_ADDRESS, the source MAC address in IHOSTS_MAC and the source registrar/region in IHOSTS_REGION.

EXAMPLES

Allow root login only from 192.168.0.x

account    required  pam_ihosts.so user=root syslog allow-ip=192.168.0.*

For all users allow login only from two mac-addresses

account    required  pam_ihosts.so user=* allow-mac=ff:c0:a8:e4:99:31,ff:c0:a8:f9:cc:01 

For all users other than root, allow login only from ip-addresses in Great Britain.

account    required  pam_ihosts.so user=!root region-files=/etc/ip-lists/delegated-afrinic-latest,/etc/ip-lists/delegated-lacnic-latest,/etc/ip-lists/delegated-apnic-latest,/etc/ip-lists/delegated-ripencc-latest allow-region=ripencc:GB

For all users, allow login only from Asia Pacific IPs.

account    required  pam_ihosts.so user=* region-files=/etc/ip-lists/delegated-afrinic-latest,/etc/ip-lists/delegated-lacnic-latest,/etc/ip-lists/delegated-apnic-latest,/etc/ip-lists/delegated-ripencc-latest allow-region=apnic:*

Same as above, but perhaps more efficient, only look up regions in the apnic file.

account    required  pam_ihosts.so user=* region-files=/etc/ip-lists/delegated-apnic-latest allow-region=apnic:*