Merge remote-tracking branch 'origin/feature/storage_passwords' into develop

Author: Sam Stelle

.gitignore

@@ -17,3 +17,5 @@ examples/*/local
 examples/*/metadata
 tests/searchcommands_data/log/
 tests/searchcommands_data/output/
+examples/searchcommands_app/searchcommand_app.log
+Test Results*.html

splunklib/binding.py

@@ -652,8 +652,7 @@ def post(self, path_segment, owner=None, app=None, sharing=None, headers=None, *
         if headers is None:
             headers = []
 
-        path = self.authority + self._abspath(path_segment, owner=owner,
-                                              app=app, sharing=sharing)
+        path = self.authority + self._abspath(path_segment, owner=owner, app=app, sharing=sharing)
         logging.debug("POST request to %s (body: %s)", path, repr(query))
         all_headers = headers + self._auth_headers
         response = self.http.post(path, all_headers, **query)

splunklib/client.py

@@ -102,44 +102,53 @@
 PATH_USERS = "authentication/users/"
 PATH_RECEIVERS_STREAM = "receivers/stream"
 PATH_RECEIVERS_SIMPLE = "receivers/simple"
+PATH_STORAGE_PASSWORDS = "storage/passwords"
 
 XNAMEF_ATOM = "{http://www.w3.org/2005/Atom}%s"
 XNAME_ENTRY = XNAMEF_ATOM % "entry"
 XNAME_CONTENT = XNAMEF_ATOM % "content"
 
 MATCH_ENTRY_CONTENT = "%s/%s/*" % (XNAME_ENTRY, XNAME_CONTENT)
 
+
 class IllegalOperationException(Exception):
     """Thrown when an operation is not possible on the Splunk instance that a
     :class:`Service` object is connected to."""
     pass
 
+
 class IncomparableException(Exception):
     """Thrown when trying to compare objects (using ``==``, ``<``, ``>``, and
     so on) of a type that doesn't support it."""
     pass
 
+
 class AmbiguousReferenceException(ValueError):
     """Thrown when the name used to fetch an entity matches more than one entity."""
     pass
 
+
 class InvalidNameException(Exception):
     """Thrown when the specified name contains characters that are not allowed
     in Splunk entity names."""
     pass
 
+
 class NoSuchCapability(Exception):
     """Thrown when the capability that has been referred to doesn't exist."""
     pass
 
+
 class OperationError(Exception):
     """Raised for a failed operation, such as a time out."""
     pass
 
+
 class NotSupportedError(Exception):
     """Raised for operations that are not supported on a given object."""
     pass
 
+
 def _trailing(template, *targets):
     """Substring of *template* following all *targets*.
 
@@ -168,6 +177,7 @@ def _trailing(template, *targets):
         s = s[n + len(t):]
     return s
 
+
 # Filter the given state content record according to the given arg list.
 def _filter_content(content, *args):
     if len(args) > 0:
@@ -180,10 +190,12 @@ def _path(base, name):
     if not base.endswith('/'): base = base + '/'
     return base + name
 
+
 # Load an atom record from the body of the given response
 def _load_atom(response, match=None):
     return data.load(response.body.read(), match)
 
+
 # Load an array of atom entries from the body of the given response
 def _load_atom_entries(response):
     r = _load_atom(response)
@@ -203,10 +215,12 @@ def _load_atom_entries(response):
         if entries is None: return None
         return entries if isinstance(entries, list) else [entries]
 
+
 # Load the sid from the body of the given response
 def _load_sid(response):
     return _load_atom(response).response.sid
 
+
 # Parse the given atom entry record into a generic entity state record
 def _parse_atom_entry(entry):
     title = entry.get('title', None)
@@ -233,6 +247,7 @@ def _parse_atom_entry(entry):
         'content': content
     })
 
+
 # Parse the metadata fields out of the given atom entry content record
 def _parse_atom_metadata(content):
     # Hoist access metadata
@@ -247,6 +262,7 @@ def _parse_atom_metadata(content):
 
     return record({'access': access, 'fields': fields})
 
+
 # kwargs: scheme, host, port, app, owner, username, password
 def connect(**kwargs):
     """This function connects and logs in to a Splunk instance.
@@ -455,6 +471,14 @@ def modular_input_kinds(self):
         else:
             raise IllegalOperationException("Modular inputs are not supported before Splunk version 5.")
 
+    @property
+    def storage_passwords(self):
+        """Returns the collection of the modular input kinds on this Splunk instance.
+
+        :return: A :class:`ReadOnlyCollection` of :class:`ModularInputKind` entities.
+        """
+        return StoragePasswords(self)
+
     # kwargs: enable_lookups, reload_macros, parse_only, output_mode
     def parse(self, query, **kwargs):
         """Parses a search query and returns a semantic map of the search.
@@ -736,11 +760,8 @@ def post(self, path_segment="", owner=None, app=None, sharing=None, **query):
         if path_segment.startswith('/'):
             path = path_segment
         else:
-            path = self.service._abspath(self.path + path_segment, owner=owner,
-                                         app=app, sharing=sharing)
-        return self.service.post(path,
-                                 owner=owner, app=app, sharing=sharing,
-                                 **query)
+            path = self.service._abspath(self.path + path_segment, owner=owner, app=app, sharing=sharing)
+        return self.service.post(path, owner=owner, app=app, sharing=sharing, **query)
 
 
 # kwargs: path, app, owner, sharing, state
@@ -819,7 +840,8 @@ def __init__(self, service, path, **kwargs):
         Endpoint.__init__(self, service, path)
         self._state = None
         if not kwargs.get('skip_refresh', False):
-            self.refresh(kwargs.get('state', None)) # "Prefresh"
+            self.refresh(kwargs.get('state', None))  # "Prefresh"
+        return
 
     def __contains__(self, item):
         try:
@@ -1273,6 +1295,7 @@ def _load_list(self, response):
                 self._entity_path(state),
                 state=state)
             entities.append(entity)
+
         return entities
 
     def itemmeta(self):
@@ -1475,7 +1498,7 @@ def create(self, name, **params):
             new_app = applications.create("my_fake_app")
         """
         if not isinstance(name, basestring):
-           raise InvalidNameException("%s is not a valid name for an entity." % name)
+            raise InvalidNameException("%s is not a valid name for an entity." % name)
         if 'namespace' in params:
             namespace = params.pop('namespace')
             params['owner'] = namespace.owner
@@ -1701,6 +1724,102 @@ def __len__(self):
                     if not x.startswith('eai') and x != 'disabled'])
 
 
+class StoragePassword(Entity):
+    """This class contains a storage password.
+    """
+    def __init__(self, service, path, **kwargs):
+        state = kwargs.get('state', None)
+        kwargs['skip_refresh'] = kwargs.get('skip_refresh', state is not None)
+        super(StoragePassword, self).__init__(service, path, **kwargs)
+        self._state = state
+
+    @property
+    def clear_password(self):
+        return self.content.get('clear_password')
+
+    @property
+    def encrypted_password(self):
+        return self.content.get('encr_password')
+
+    @property
+    def realm(self):
+        return self.content.get('realm')
+
+    @property
+    def username(self):
+        return self.content.get('username')
+
+
+class StoragePasswords(Collection):
+    """This class provides access to the storage passwords from this Splunk
+    instance. Retrieve this collection using :meth:`Service.storage_passwords`.
+    """
+    def __init__(self, service):
+        if service.namespace.owner == '-' or service.namespace.app == '-':
+            raise ValueError("StoragePasswords cannot have wildcards in namespace.")
+        super(StoragePasswords, self).__init__(service, PATH_STORAGE_PASSWORDS, item=StoragePassword)
+
+    def create(self, password, username, realm=None):
+        """ Creates a storage password.
+
+        A `StoragePassword` can be identified by <username>, or by <realm>:<username> if the
+        optional realm parameter is also provided.
+
+        :param password: The password for the credentials - this is the only part of the credentials that will be stored securely.
+        :type name: ``string``
+        :param username: The username for the credentials.
+        :type name: ``string``
+        :param realm: The credential realm. (optional)
+        :type name: ``string``
+
+        :return: The :class:`StoragePassword` object created.
+        """
+        if not isinstance(username, basestring):
+            raise ValueError("Invalid name: %s" % repr(username))
+
+        if realm is None:
+            response = self.post(password=password, name=username)
+        else:
+            response = self.post(password=password, realm=realm, name=username)
+
+        if response.status != 201:
+            raise ValueError("Unexpected status code %s returned from creating a stanza" % response.status)
+
+        entries = _load_atom_entries(response)
+        state = _parse_atom_entry(entries[0])
+        storage_password = StoragePassword(self.service, self._entity_path(state), state=state, skip_refresh=True)
+
+        return storage_password
+    
+    def delete(self, username, realm=None):
+        """Delete a storage password by username and/or realm.
+
+        The identifier can be passed in through the username parameter as
+        <username> or <realm>:<username>, but the preferred way is by
+        passing in the username and realm parameters.
+
+        :param username: The username for the credentials, or <realm>:<username> if the realm parameter is omitted.
+        :type name: ``string``
+        :param realm: The credential realm. (optional)
+        :type name: ``string``
+        :return: The `StoragePassword` collection.
+        :rtype: ``self``
+        """
+        if realm is None:
+            # This case makes the username optional, so
+            # the full name can be passed in as realm.
+            # Assume it's already encoded.
+            name = username
+        else:
+            # Encode each component separately
+            name = UrlEncoded(realm, encode_slash=True) + ":" + UrlEncoded(username, encode_slash=True)
+
+        # Append the : expected at the end of the name
+        if name[-1] is not ":":
+            name = name + ":"
+        return Collection.delete(self, name)
+
+
 class AlertGroup(Entity):
     """This class represents a group of fired alerts for a saved search. Access
     it using the :meth:`alerts` property."""

splunklib/searchcommands/decorators.py

@@ -222,8 +222,9 @@ def __repr__(self):
             return str(self)
 
         def __str__(self):
+            value = self.validator.format(self.value) if self.validator is not None else str(self.value)
             encoder = Option.Encoder(self)
-            text = '='.join([self.name, encoder.encode(self.value)])
+            text = '='.join([self.name, encoder.encode(value)])
             return text
 
         #region Properties