aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBen Burwell <ben@benburwell.com>2018-02-23 23:08:51 -0500
committerBen Burwell <ben@benburwell.com>2018-02-24 00:31:17 -0500
commit335dfdffecf8385044a585ff2b8f1b671e894ae7 (patch)
tree1f84e928e66f1374df34078f094b152e27db4b3f
parent6ec8b3e334dd35dd8c7a168d3a182a5bd3289c9f (diff)
Update documentationHEADv0.1.0master
-rw-r--r--LICENSE22
-rw-r--r--Makefile29
-rw-r--r--README.md27
-rwxr-xr-xaudit.bash13
-rw-r--r--pass-audit.1166
5 files changed, 254 insertions, 3 deletions
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.
+