From 335dfdffecf8385044a585ff2b8f1b671e894ae7 Mon Sep 17 00:00:00 2001 From: Ben Burwell Date: Fri, 23 Feb 2018 23:08:51 -0500 Subject: Update documentation --- LICENSE | 22 ++++++++ Makefile | 29 +++++++++++ README.md | 27 ++++++++++ audit.bash | 13 +++-- pass-audit.1 | 166 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 254 insertions(+), 3 deletions(-) create mode 100644 LICENSE create mode 100644 Makefile create mode 100644 README.md create mode 100644 pass-audit.1 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..7ded667 --- /dev/null +++ b/LICENSE @@ -0,0 +1,22 @@ +MIT License + +Copyright (c) 2018 Ben Burwell + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..18e949a --- /dev/null +++ b/Makefile @@ -0,0 +1,29 @@ +PREFIX ?= /usr +LIB_DIR ?= $(PREFIX)/lib +EXTENSION_DIR ?= $(LIB_DIR)/password-store/extensions +MAN_DIR ?= $(PREFIX)/share/man + +info: + @echo "pass-audit is a shell script that goes into your pass extensions" + @echo "folder" + @echo "" + @echo "To install, simply run \"make install\". On macOS, you will need to" + @echo "run \"make install PREFIX=/usr/local\"." + @echo "" + @echo "To use pass-audit, you will beed to install password store" + @echo "(https://www.passwordstore.org/)" + +install: + @install -v -d "$(MAN_DIR)/man1" && install -m 0644 -v pass-audit.1 "$(MAN_DIR)/man1/pass-audit.1" + @install -v -d "$(EXTENSION_DIR)/" && install -m 0755 audit.bash "$(EXTENSION_DIR)/audit.bash" + @echo "pass-audit has been installed." + @echo "" + @echo "Try running \"pass audit --help\" or \"man pass-audit\" for info." + +uninstall: + @rm -vrf \ + "$(MAN_DIR)/man1/pass-audit.1" \ + "$(EXTENSION_DIR)/audit.bash" + +.PHONY: info install uninstall + diff --git a/README.md b/README.md new file mode 100644 index 0000000..e2d4592 --- /dev/null +++ b/README.md @@ -0,0 +1,27 @@ +# pass-audit - an extension for the [`pass` password store](https://www.passwordstore.org/) + +`pass-audit` helps you check your passwords against known vulnerable ones +included in the [Have I Been Pwned (HIBP) list of exposed +passwords](https://haveibeenpwned.com/Passwords). + +## Installation + +``` +git clone https://github.com/benburwell/pass-audit.git +cd pass-audit +sudo make install +``` + +**Note:** On macOS, you will need to use `sudo make install PREFIX=/usr/local` +instead of `sudo make install`. + +## Usage + +Check all your passwords against the HIBP database: + +``` +pass audit all --hibp +``` + +For more examples, see `man pass-audit`. + diff --git a/audit.bash b/audit.bash index b7de93e..3c424f3 100755 --- a/audit.bash +++ b/audit.bash @@ -83,12 +83,12 @@ cmd_audit_usage () { cat <<-_EOF Usage: - $PROGRAM audit [--hibp,-p] [--wordlist,-w list-file] pass-name + $PROGRAM audit [ check ] [ --hibp ] [ --wordlist=list-file ] pass-name Check whether a password has been pwned, either by consulting Have I Been Pwned or a wordlist file (or both). You can specify either or both options, but without at least one, nothing will happen. - $PROGRAM audit all [--hibp,-p] [--wordlist,-w list-file] + $PROGRAM audit all [ --hibp ] [ --wordlist=list-file ] Check all the passwords in your store against Have I Been Pwned and/or the provided wordlist. @@ -97,9 +97,16 @@ _EOF exit 0 } +cmd_audit_version () { + echo "pass-audit v0.1.0" + exit 0 +} + case "$1" in + version) shift; cmd_audit_version "$@" ;; help|--help|-h) shift; cmd_audit_usage "$@" ;; - --all) shift; cmd_audit_all_passwords "$@" ;; + all) shift; cmd_audit_all_passwords "$@" ;; + check) shift; cmd_audit_password "$@" ;; *) cmd_audit_password "$@" ;; esac diff --git a/pass-audit.1 b/pass-audit.1 new file mode 100644 index 0000000..c04fca9 --- /dev/null +++ b/pass-audit.1 @@ -0,0 +1,166 @@ +.TH PASS-AUDIT 1 "2018 February 23" "Password store audit extension" + +.SH NAME +pass-audit - A \fBpass\fP(1) extension for checking password strength. + +.SH SYNOPSIS +.B pass audit +[ +.I COMMAND +] +[ +.I OPTIONS +] [ +.I ARGS +] + +.SH DESCRIPTION + +.B pass-audit +is an extension for +.BR pass (1) +to help find passwords in your store which may be vulnerable. +.B pass-audit +currently has two mechanisms for checking a password: + +.IP \[bu] +.B Have I Been Pwned (HIBP) + +.B pass-audit +can check HIBP to see whether a password is included in the large repository of +pwned passwords. The HIBP password API has been carefully designed to prevent +significant password data from leaving the local machine. To accomplish this, +the password is hashed using SHA1 and a request is made to +.BI https://api.pwnedpasswords.com/range/ RANGE +where +.I RANGE +is the first 5 hexadecimal digits of the SHA1 digest. + +This URL returns a list of SHA1 hashes of pwned passwords beginning with +.IR RANGE . +.B pass-audit +then searches locally in the hashes returned from the API for the hash of the +password being checked. Using this technique, the only data that leaves the +local machine is the first five digits of the SHA1 digest of each password +being audited. + +.IP \[bu] +.B Local wordlist + +.B pass-audit +can check your passwords against a local wordlist. The password being checked is tested against each pattern in the specified wordlist file using +.BR grep (1) +with the +.B --file +option. + +If a password is found to be vulnerable, the name of the password is printed to standard output and +.B pass-audit +will exit with a return code of +.BR 1 . +This is to aid in scripting tasks, such as compiling a list of your vulnerable passwords. + +.SH COMMANDS + +.TP +.B check +Check a password for vulnerability. This is the default option; if no +.B COMMAND +is specified, then +.B check +will be run. + +.TP +.B all +Check all the passwords in your store for vulnerability. + +.TP +.B help +Display help about +.BR pass-audit . + +.TP +.B version +Display the version of +.BR pass-audit . + +.SH OPTIONS + +.TP +.B --hibp +Use the Have I Been Pwned service to check whether the password may be vulnerable. + +.TP +.BI --wordlist= word-file +Use the +.I word-file +file to check the password. + +.SH USAGE + +.TP +\fBpass audit\fP [ \fBcheck\fP ] [ \fB--hibp\fP ] [ \fB--wordlist=\fP\fIword-file\fP ] \fIpass-name\fP +Check whether +.I pass-name +is vulnerable according to HIBP, the supplied +.IR word-file , +or both. + +.TP +\fBpass audit all\fP [ \fB--hibp\fP ] [ \fB--wordlist=\fP\fIword-file\fP ] +Check each password in your store to see whether it may be vulnerable according to HIBP, the supplied +.IR word-file , +or both. + +.SH EXAMPLES + +.TP +.B pass audit all --wordlist=/usr/share/wordlists/rockyou.txt +Check all passwords in the store against the rockyou wordlist. + +.TP +.B pass audit --hibp github.com +Check your password for GitHub to see if it is included in the HIBP list using the online API. + +.TP +.B pass audit check --wordlist=/usr/share/dict/words github.com +Check your password for GitHub to see if it is a dictionary word. + +.SH SEE ALSO +.BR pass (1), +.BR grep (1), +.BR curl (1), +.BR shasum (1) + +.SH BUGS +Issues encountered or improvements for +.B pass-audit +may be submitted to https://github.com/benburwell/pass-audit/issues. + +.SH AUTHOR +.B pass-audit +was written by Ben Burwell. + +.SH COPYING +MIT License + +Copyright (c) 2018 Ben Burwell + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + -- cgit v1.2.3