Update documentationHEADv0.1.0master

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.
+