#!/usr/bin/env perl

# vim: set nosta noet ts=4 sw=4:

#

# Copyright (c) 2006-2019, Mahlon E. Smith <mahlon@martini.nu>

# All rights reserved.

# Redistribution and use in source and binary forms, with or without

# modification, are permitted provided that the following conditions are met:

#

#     * Redistributions of source code must retain the above copyright

#       notice, this list of conditions and the following disclaimer.

#

#     * Redistributions in binary form must reproduce the above copyright

#       notice, this list of conditions and the following disclaimer in the

#       documentation and/or other materials provided with the distribution.

#

#     * Neither the name of Mahlon E. Smith nor the names of his

#       contributors may be used to endorse or promote products derived

#       from this software without specific prior written permission.

#

# THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY

# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED

# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

# DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY

# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES

# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;

# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND

# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

=head1 NAME

Shelldap - A program for interacting with an LDAP server via a shell-like interface

=head1 DESCRIPTION

Shelldap /LDAP::Shell is a program for interacting with an LDAP server via a shell-like

interface.

This is not meant to be an exhaustive LDAP editing and browsing

interface, but rather an intuitive shell for performing basic LDAP

tasks quickly and with minimal effort.

=head1 SYNPOSIS

 shelldap --server example.net [--help]

=head1 FEATURES

 - Upon successful authenticated binding, credential information is

   auto-cached to ~/.shelldap.rc -- future loads require no command line

   flags.

 - Custom 'description maps' for entry listings.  (See the 'list' command.)

 - History and autocomplete via readline, if installed.

 - Automatic reconnection attempts if the connection is lost with the

   LDAP server.

 - Basic schema introspection for quick reference.

 - It feels like a semi-crippled shell, making LDAP browsing and editing

   at least halfway pleasurable.

=head1 OPTIONS

All command line options follow getopts long conventions.

    shelldap --server example.net --basedn dc=your,o=company

You may also optionally create a ~/.shelldap.rc file with command line

defaults.  This file should be valid YAML.  (This file is generated

automatically on a successful bind auth.)

Example:

    server: ldap.example.net

    binddn: cn=Manager,dc=your,o=company

    bindpass: xxxxxxxxx

    basedn: dc=your,o=company

    tls: yes

    tls_cacert: /etc/ssl/certs/cacert.pem

    tls_cert:   ~/.ssl/client.cert.pem 

    tls_key:    ~/.ssl/private/client.key.pem

=over 4

=item B<configfile>

Optional.  Use an alternate configuration file, instead of the

default ~/.shelldap.rc.

    --configfile /tmp/alternate-config.yml

    -f /tmp/alternate-config.yml

This config file overrides values found in the default config, so

you can easily have separate config files for connecting to your

cn=monitor or cn=log overlays (for example.)

=back

=over 4

=item B<server>

Required. The LDAP server to connect to.  This can be a hostname, IP

address, or a URI.

    --server ldaps://ldap.example.net

    -H ldaps://ldap.example.net

=back

=over 4

=item B<binddn>

The full dn of a user to authenticate as.  If not specified, defaults to

an anonymous bind.  You will be prompted for a password.

    --binddn cn=Manager,dc=your,o=company

    -D cn=Manager,dc=your,o=company

=back

=over 4

=item B<basedn>

The directory 'root' of your LDAP server.  If omitted, shelldap will

try and ask the server for a sane default.

    --basedn dc=your,o=company

    -b dc=your,o=company

=back

=over 4

=item B<paginate>

Integer.  If enabled, shelldap will attempt to use server side

pagination to build listings.  Note: if you're using this to avoid

sizelimit errors, you'll likely need server configuration to raise the

limits for paginated results.

	--paginate 100

=back

=over 4

=item B<promptpass>

Force password prompting.  Useful to temporarily override cached

credentials.

=back

=over 4

=item B<sasl>

A space separated list of SASL mechanisms.  Requires the Authen::SASL

module.

    --sasl "PLAIN CRAM-MD5 GSSAPI"

=back

=over 4

=item B<tls>

Enables TLS over what would normally be an insecure connection.

Requires server side support.

=item B<tls_cacert>

Specify CA Certificate to trust.

    --tls_cacert /etc/ssl/certs/cacert.pem

=item B<tls_cert>

The TLS client certificate.

    --tls_cert ~/.ssl/client.cert.pem

=item B<tls_key>

The TLS client key.  Not specifying a key will connect via TLS without

key verification.

    --tls_key ~/.ssl/private/client.key.pem

=back

=over 4

=item B<cacheage>

Set the time to cache directory lookups in seconds.

By default, directory lookups are cached for 300 seconds, to speed

autocomplete up when changing between different basedns.

Modifications to the directory automatically reset the cache.  Directory

listings are not cached.  (This is just used for autocomplete.)  Set it

to 0 to disable caching completely.

=back

=over 4

=item B<timeout>

Set the maximum time an LDAP operation can take before it is cancelled.

=back

=over 4

=item B<debug>

Print extra operational info out, and backtrace on fatal error.

=back

=over 4

=item B<version>

Display the version number.

=back

=head1 SHELL COMMANDS

=over 4

=item B< cat>

Display an LDIF dump of an entry.  Globbing is supported.  Specify

either the full dn, or an rdn.  For most commands, rdns are local to the

current search base. ('cwd', as translated to shell speak.)  You may additionally

add a list of attributes to display.  Use '+' for server side attributes.

    cat uid=mahlon

    cat ou=*

    cat uid=mahlon,ou=People,dc=example,o=company

    cat uid=mahlon + userPassword

=item B< less>

Like cat, but uses the configured pager to display output.

=item B<  cd>

Change directory.  Translated to LDAP, this changes the current basedn.

All commands after a 'cd' operate within the new basedn.

    cd                  change to 'home' basedn

    cd ~                change to the binddn, or basedn if anonymously bound

    cd -                change to previous node

    cd ou=People        change to explicit path below current node

    cd ..               change to parent node

    cd ../../ou=Groups  change to node ou=Groups, which is a sibling

                        to the current node's grandparent

Since LDAP doesn't actually limit what can be a container object, you

can actually cd into any entry. Many commands then work on '.', meaning

"wherever I currently am."

    cd uid=mahlon

    cat .

=item B<clear>

Clear the screen.

=item B<copy>

Copy an entry to a different dn path.  All copies are relative to the

current basedn, unless a full dn is specified.  All attributes are

copied, then an LDAP moddn() is performed.

    copy uid=mahlon uid=bob

    copy uid=mahlon ou=Others,dc=example,o=company

    copy uid=mahlon,ou=People,dc=example,o=company uid=mahlon,ou=Others,dc=example,o=company

aliased to: cp

=item B<create>

Create an entry from scratch.  Arguments are space separated objectClass

names.  Possible objectClasses are derived automatically from the

server, and will tab-complete.

After the classes are specified, an editor will launch.  Required

attributes are listed first, then optional attributes.  Optionals are

commented out.  After the editor exits, the resulting LDIF is validated

and added to the LDAP directory.

    create top person organizationalPerson inetOrgPerson posixAccount

aliased to: touch

=item B<delete>

Remove an entry from the directory.  Globbing is supported.

All deletes are sanity-prompted.  The -v flag prints the entries out

for review before delete.

    delete uid=mahlon

    delete uid=ma*

    rm -v uid=mahlon,ou=People,dc=example,o=company l=office

aliased to: rm

=item B<edit>

Edit an entry in an external editor.  After the editor exits, the

resulting LDIF is sanity checked, and changes are written to the LDAP

directory.

    edit uid=mahlon

aliased to: vi

=item B<env>

 Show values for various runtime variables.

=item B<grep>

Search for arbitrary LDAP filters, and return matching dn results.

The search string must be a valid LDAP filter.

    grep uid=mahlon

    grep uid=mahlon ou=People

    grep -r (&(uid=mahlon)(objectClass=*))

 aliased to: search

=item B<inspect>

View schema information about a given entry, or a list of arbitrary

objectClasses, along with the most common flags for the objectClass

attributes.

    inspect uid=mahlon

    inspect posixAccount organizationalUnit

    inspect _schema

The output is a list of found objectClasses, their schema hierarchy

(up to 'top'), whether or not they are a structural class, and then

a merged list of all valid attributes for the given objectClasses.

Attributes are marked as either required or optional, and whether

they allow multiple values or not.

If you ask for the special "_schema" object, the raw server schema

is dumped to screen.

=item B<list>

List entries for the current basedn.  Globbing is supported.

aliased to: ls

    ls -l

    ls -lR uid=mahlon

    list uid=m*

In 'long' mode, descriptions are listed as well, if they exist.

There are some default 'long listing' mappings for common objectClass

types.  You can additionally specify your own mappings in your

.shelldap.rc, like so:

    ...

    descmaps:

        objectClass: attributename

        posixAccount: gecos

        posixGroup: gidNumber

        ipHost: ipHostNumber

=item B<mkdir>

Creates a new 'organizationalUnit' entry.

    mkdir containername

    mkdir ou=whatever

=item B<move>

Move an entry to a different dn path.  Usage is identical to B<copy>.

aliased to: mv

=item B<passwd>

If supported server side, change the password for a specified entry.

The entry must have a 'userPassword' attribute.

    passwd uid=mahlon

=item B< pwd>

Print the 'working directory' - aka, the current ldap basedn.

=item B<setenv>

Modify various runtime variables normally set from the command line.

    setenv debug 1

    export debug=1

=item B<whoami>

Show current auth credentials.  Unless you specified a binddn, this

will just show an anonymous bind.

aliased to: id

=back

=head1 TODO

Referral support.  Currently, if you try to write to a replicant slave,

you'll just get a referral.  It would be nice if shelldap automatically

tried to follow it.

For now, it only makes sense to connect to a master if you plan on doing

any writes.

=head1 BUGS / LIMITATIONS

There is no support for editing binary data.  If you need to edit base64

stuff, just feed it to the regular ldapmodify/ldapadd/etc tools.

=head1 AUTHOR

Mahlon E. Smith <mahlon@martini.nu>

=cut

package LDAP::Shell;

use strict;

use warnings;

use Term::ReadKey;

use Term::Shell;

use Digest::MD5;

use Net::LDAP qw/

	LDAP_SUCCESS

	LDAP_SERVER_DOWN

	LDAP_OPERATIONS_ERROR

	LDAP_TIMELIMIT_EXCEEDED

	LDAP_BUSY

	LDAP_UNAVAILABLE

	LDAP_OTHER

	LDAP_TIMEOUT

	LDAP_NO_MEMORY

	LDAP_EXTENSION_PASSWORD_MODIFY

	LDAP_CONNECT_ERROR

	LDAP_CONTROL_PAGED /;

use Net::LDAP::Util qw/ canonical_dn ldap_explode_dn /;

use Net::LDAP::LDIF;

use Net::LDAP::Extension::SetPassword;

use Net::LDAP::Control::Paged;

use Data::Dumper;

use File::Temp;

use Algorithm::Diff;

use Carp 'confess';

use base 'Term::Shell';

my $conf = $main::conf;

# make 'die' backtrace in debug mode

$SIG{'__DIE__'} = \&Carp::confess if $conf->{'debug'};

########################################################################

### U T I L I T Y   F U N C T I O N S

########################################################################

### Initial shell behaviors.

### 

sub init

{

	my $self = shift;

	$self->{'API'}->{'match_uniq'} = 0;

	$self->{'editor'} = $conf->{'editor'} || $ENV{'EDITOR'} || 'vi';

	$self->{'pager'}  = $conf->{'pager'}  || $ENV{'PAGER'}  || 'less';

	$self->{'env'}	  = [ qw/ debug cacheage timeout / ];

	# let autocomplete work with the '=' character

	my $term = $self->term();

	$term->Attribs->{'basic_word_break_characters'}	 =~ s/=//m;

	$term->Attribs->{'completer_word_break_characters'} =~ s/=//m;

	# read in history

	eval {

		$term->history_truncate_file("$ENV{'HOME'}/.shelldap_history", 50);

		$term->ReadHistory("$ENV{'HOME'}/.shelldap_history");

	};

	# gather metadata from the LDAP server

	$self->{'root_dse'} = $self->ldap->root_dse() or

		die "Unable to retrieve LDAP server information.  (Doublecheck connection arguments.)\n";