def testAddMonitor(self): b = MonitoredBuffer() # Set the monitor callback up. def monitor_cb(thedata, *args, **kwargs): thedata['args'] = args thedata['kwargs'] = kwargs data = {} b.add_monitor('abc', partial(monitor_cb, data)) # Test some non-matching data. b.append('aaa') self.assertEqual(data, {}) b.append('aaa') self.assertEqual(data, {}) # Test some matching data. b.append('abc') self.assertEqual(len(data.get('args')), 2) self.assertEqual(data.get('args')[0], 0) self.assertEqual(data.get('args')[1].group(0), 'abc') self.assertEqual(data.get('kwargs'), {}) # Make sure that the same monitor is not called again. data.pop('args') data.pop('kwargs') b.append('bbb') self.assertEqual(data, {}) # Test some matching data. b.append('abc') self.assertEqual(len(data.get('args')), 2) self.assertEqual(data.get('args')[0], 0) self.assertEqual(data.get('args')[1].group(0), 'abc') self.assertEqual(data.get('kwargs'), {})
def testSize(self): b = MonitoredBuffer() self.assertEqual(b.size(), 0) b.append('foo') self.assertEqual(b.size(), 3) b.append('bar') self.assertEqual(b.size(), 6)
def testSize(self): b = MonitoredBuffer() self.assertEqual(b.size(), 0) b.append('foo') self.assertEqual(b.size(), 3) b.append('bar') self.assertEqual(b.size(), 6)
def testAddMonitor(self): b = MonitoredBuffer() # Set the monitor callback up. def monitor_cb(thedata, *args, **kwargs): thedata['args'] = args thedata['kwargs'] = kwargs data = {} b.add_monitor('abc', partial(monitor_cb, data)) # Test some non-matching data. b.append('aaa') self.assertEqual(data, {}) b.append('aaa') self.assertEqual(data, {}) # Test some matching data. b.append('abc') self.assertEqual(len(data.get('args')), 2) self.assertEqual(data.get('args')[0], 0) self.assertEqual(data.get('args')[1].group(0), 'abc') self.assertEqual(data.get('kwargs'), {}) # Make sure that the same monitor is not called again. data.pop('args') data.pop('kwargs') b.append('bbb') self.assertEqual(data, {}) # Test some matching data. b.append('abc') self.assertEqual(len(data.get('args')), 2) self.assertEqual(data.get('args')[0], 0) self.assertEqual(data.get('args')[1].group(0), 'abc') self.assertEqual(data.get('kwargs'), {})
def testClear(self): b = MonitoredBuffer() self.assertEqual(str(b), '') b.append('foo') self.assertEqual(str(b), 'foo') b.clear() self.assertEqual(str(b), '') b.clear() self.assertEqual(str(b), '')
def testClear(self): b = MonitoredBuffer() self.assertEqual(str(b), '') b.append('foo') self.assertEqual(str(b), 'foo') b.clear() self.assertEqual(str(b), '') b.clear() self.assertEqual(str(b), '')
def testTail(self): b = MonitoredBuffer() self.assertEqual(str(b), '') self.assertEqual(b.tail(0), '') self.assertEqual(b.tail(10), '') b.append('foobar') self.assertEqual(str(b), 'foobar') self.assertEqual(b.tail(0), '') self.assertEqual(b.tail(1), 'r') self.assertEqual(b.tail(6), 'foobar') self.assertEqual(b.tail(10), 'foobar')
def testHead(self): b = MonitoredBuffer() self.assertEqual(str(b), '') self.assertEqual(b.head(0), '') self.assertEqual(b.head(10), '') b.append('foobar') self.assertEqual(str(b), 'foobar') self.assertEqual(b.head(0), '') self.assertEqual(b.head(1), 'f') self.assertEqual(b.head(6), 'foobar') self.assertEqual(b.head(10), 'foobar')
def testTail(self): b = MonitoredBuffer() self.assertEqual(str(b), '') self.assertEqual(b.tail(0), '') self.assertEqual(b.tail(10), '') b.append('foobar') self.assertEqual(str(b), 'foobar') self.assertEqual(b.tail(0), '') self.assertEqual(b.tail(1), 'r') self.assertEqual(b.tail(6), 'foobar') self.assertEqual(b.tail(10), 'foobar')
def testHead(self): b = MonitoredBuffer() self.assertEqual(str(b), '') self.assertEqual(b.head(0), '') self.assertEqual(b.head(10), '') b.append('foobar') self.assertEqual(str(b), 'foobar') self.assertEqual(b.head(0), '') self.assertEqual(b.head(1), 'f') self.assertEqual(b.head(6), 'foobar') self.assertEqual(b.head(10), 'foobar')
def testPop(self): b = MonitoredBuffer() self.assertEqual(str(b), '') self.assertEqual(b.pop(0), '') self.assertEqual(str(b), '') self.assertEqual(b.pop(10), '') self.assertEqual(str(b), '') b.append('foobar') self.assertEqual(str(b), 'foobar') self.assertEqual(b.pop(0), '') self.assertEqual(str(b), 'foobar') self.assertEqual(b.pop(2), 'fo') self.assertEqual(str(b), 'obar') b.append('doh') self.assertEqual(b.pop(10), 'obardoh') self.assertEqual(str(b), '')
def testPop(self): b = MonitoredBuffer() self.assertEqual(str(b), '') self.assertEqual(b.pop(0), '') self.assertEqual(str(b), '') self.assertEqual(b.pop(10), '') self.assertEqual(str(b), '') b.append('foobar') self.assertEqual(str(b), 'foobar') self.assertEqual(b.pop(0), '') self.assertEqual(str(b), 'foobar') self.assertEqual(b.pop(2), 'fo') self.assertEqual(str(b), 'obar') b.append('doh') self.assertEqual(b.pop(10), 'obardoh') self.assertEqual(str(b), '')
def testAppend(self): b = MonitoredBuffer() self.assertEqual(str(b), '') b.append('foo') self.assertEqual(str(b), 'foo') b.append('bar') self.assertEqual(str(b), 'foobar') b.append('doh') self.assertEqual(str(b), 'foobardoh')
def testAppend(self): b = MonitoredBuffer() self.assertEqual(str(b), '') b.append('foo') self.assertEqual(str(b), 'foo') b.append('bar') self.assertEqual(str(b), 'foobar') b.append('doh') self.assertEqual(str(b), 'foobardoh')
class Protocol(object): """ This is the base class for all protocols; it defines the common portions of the API. The goal of all protocol classes is to provide an interface that is unified across protocols, such that the adapters may be used interchangeably without changing any other code. In order to achieve this, the main challenge are the differences arising from the authentication methods that are used. The reason is that many devices may support the following variety authentication/authorization methods: 1. Protocol level authentication, such as SSH's built-in authentication. - p1: password only - p2: username - p3: username + password - p4: username + key - p5: username + key + password 2. App level authentication, such that the authentication may happen long after a connection is already accepted. This type of authentication is normally used in combination with Telnet, but some SSH hosts also do this (users have reported devices from Enterasys). These devices may also combine protocol-level authentication with app-level authentication. The following types of app-level authentication exist: - a1: password only - a2: username - a3: username + password 3. App level authorization: In order to implement the AAA protocol, some devices ask for two separate app-level logins, whereas the first serves to authenticate the user, and the second serves to authorize him. App-level authorization may support the same methods as app-level authentication: - A1: password only - A2: username - A3: username + password We are assuming that the following methods are used: - Telnet: - p1 - p5: never - a1 - a3: optional - A1 - A3: optional - SSH: - p1 - p5: optional - a1 - a3: optional - A1 - A3: optional To achieve authentication method compatibility across different protocols, we must hide all this complexity behind one single API call, and figure out which ones are supported. As a use-case, our goal is that the following code will always work, regardless of which combination of authentication methods a device supports:: key = PrivateKey.from_file('~/.ssh/id_rsa', 'my_key_password') # The user account to use for protocol level authentication. # The key defaults to None, in which case key authentication is # not attempted. account = Account(name = 'myuser', password = '******', key = key) # The account to use for app-level authentication. # password2 defaults to password. app_account = Account(name = 'myuser', password = '******', password2 = 'my_app_password2') # app_account defaults to account. conn.login(account, app_account = None, flush = True) Another important consideration is that once the login is complete, the device must be in a clearly defined state, i.e. we need to have processed the data that was retrieved from the connected host. More precisely, the buffer that contains the incoming data must be in a state such that the following call to expect_prompt() will either always work, or always fail. We hide the following methods behind the login() call:: # Protocol level authentication. conn.protocol_authenticate(...) # App-level authentication. conn.app_authenticate(...) # App-level authorization. conn.app_authorize(...) The code produces the following result:: Telnet: conn.protocol_authenticate -> NOP conn.app_authenticate -> waits for username or password prompt, authenticates, returns after a CLI prompt was seen. conn.app_authorize -> calls driver.enable(), waits for username or password prompt, authorizes, returns after a CLI prompt was seen. SSH: conn.protocol_authenticate -> authenticates using user/key/password conn.app_authenticate -> like Telnet conn.app_authorize -> like Telnet We can see the following: - protocol_authenticate() must not wait for a prompt, because else app_authenticate() has no way of knowing whether an app-level login is even necessary. - app_authenticate() must check the buffer first, to see if authentication has already succeeded. In the case that app_authenticate() is not necessary (i.e. the buffer contains a CLI prompt), it just returns. app_authenticate() must NOT eat the prompt from the buffer, because else the result may be inconsistent with devices that do not do any authentication; i.e., when app_authenticate() is not called. - Since the prompt must still be contained in the buffer, conn.driver.app_authorize() needs to eat it before it sends the command for starting the authorization procedure. This has a drawback - if a user attempts to call app_authorize() at a time where there is no prompt in the buffer, it would fail. So we need to eat the prompt only in cases where we know that auto_app_authorize() will attempt to execute a command. Hence the driver requires the Driver.supports_auto_authorize() method. However, app_authorize() must not eat the CLI prompt that follows. - Once all logins are processed, it makes sense to eat the prompt depending on the wait parameter. Wait should default to True, because it's better that the connection stalls waiting forever, than to risk that an error is not immediately discovered due to timing issues (this is a race condition that I'm not going to detail here). """ def __init__(self, driver = None, stdout = None, stderr = None, debug = 0, timeout = 30, logfile = None, termtype = 'dumb', verify_fingerprint = True, account_factory = None): """ Constructor. The following events are provided: - data_received_event: A packet was received from the connected host. - otp_requested_event: The connected host requested a one-time-password to be entered. @keyword driver: passed to set_driver(). @keyword stdout: Where to write the device response. Defaults to os.devnull. @keyword stderr: Where to write debug info. Defaults to stderr. @keyword debug: An integer between 0 (no debugging) and 5 (very verbose debugging) that specifies the amount of debug info sent to the terminal. The default value is 0. @keyword timeout: See set_timeout(). The default value is 30. @keyword logfile: A file into which a log of the conversation with the device is dumped. @keyword termtype: The terminal type to request from the remote host, e.g. 'vt100'. @keyword verify_fingerprint: Whether to verify the host's fingerprint. @keyword account_factory: A function that produces a new L{Account}. """ self.data_received_event = Event() self.otp_requested_event = Event() self.os_guesser = OsGuesser() self.auto_driver = driver_map[self.guess_os()] self.proto_authenticated = False self.app_authenticated = False self.app_authorized = False self.manual_user_re = None self.manual_password_re = None self.manual_prompt_re = None self.manual_error_re = None self.manual_login_error_re = None self.driver_replaced = False self.host = None self.port = None self.last_account = None self.termtype = termtype self.verify_fingerprint = verify_fingerprint self.manual_driver = driver self.debug = debug self.timeout = timeout self.logfile = logfile self.response = None self.buffer = MonitoredBuffer() self.account_factory = account_factory if stdout is None: self.stdout = open(os.devnull, 'w') else: self.stdout = stdout if stderr is None: self.stderr = sys.stderr else: self.stderr = stderr if logfile is None: self.log = None else: self.log = open(logfile, 'a') def __copy__(self): """ Overwritten to return the very same object instead of copying the stream, because copying a network connection is impossible. @rtype: Protocol @return: self """ return self def __deepcopy__(self, memo): """ Overwritten to return the very same object instead of copying the stream, because copying a network connection is impossible. @type memo: object @param memo: Please refer to Python's standard library documentation. @rtype: Protocol @return: self """ return self def _driver_replaced_notify(self, old, new): self.driver_replaced = True self.cancel_expect() msg = 'Protocol: driver replaced: %s -> %s' % (old.name, new.name) self._dbg(1, msg) def _receive_cb(self, data, remove_cr = True): # Clean the data up. if remove_cr: text = data.replace('\r', '') else: text = data # Write to a logfile. self.stdout.write(text) self.stdout.flush() if self.log is not None: self.log.write(text) # Check whether a better driver is found based on the incoming data. old_driver = self.get_driver() self.os_guesser.data_received(data, self.is_app_authenticated()) self.auto_driver = driver_map[self.guess_os()] new_driver = self.get_driver() if old_driver != new_driver: self._driver_replaced_notify(old_driver, new_driver) # Send signals to subscribers. self.data_received_event(data) def is_dummy(self): """ Returns True if the adapter implements a virtual device, i.e. it isn't an actual network connection. @rtype: Boolean @return: True for dummy adapters, False for network adapters. """ return False def _dbg(self, level, msg): if self.debug < level: return self.stderr.write(self.get_driver().name + ': ' + msg + '\n') def set_driver(self, driver = None): """ Defines the driver that is used to recognize prompts and implement behavior depending on the remote system. The driver argument may be an subclass of protocols.drivers.Driver, a known driver name (string), or None. If the driver argument is None, the adapter automatically chooses a driver using the guess_os() function. @type driver: Driver|str @param driver: The pattern that, when matched, causes an error. """ if driver is None: self.manual_driver = None elif isinstance(driver, str): if driver not in driver_map: raise TypeError('no such driver:' + repr(driver)) self.manual_driver = driver_map[driver] elif isdriver(driver): self.manual_driver = driver else: raise TypeError('unsupported argument type:' + type(driver)) def get_driver(self): """ Returns the currently used driver. @rtype: Driver @return: A regular expression. """ if self.manual_driver: return self.manual_driver return self.auto_driver def autoinit(self): """ Make the remote host more script-friendly by automatically executing one or more commands on it. The commands executed depend on the currently used driver. For example, the driver for Cisco IOS would execute the following commands:: term len 0 term width 0 """ self.get_driver().init_terminal(self) def set_username_prompt(self, regex = None): """ Defines a pattern that is used to monitor the response of the connected host for a username prompt. @type regex: RegEx @param regex: The pattern that, when matched, causes an error. """ if regex is None: self.manual_user_re = regex else: self.manual_user_re = to_regexs(regex) def get_username_prompt(self): """ Returns the regular expression that is used to monitor the response of the connected host for a username prompt. @rtype: regex @return: A regular expression. """ if self.manual_user_re: return self.manual_user_re return self.get_driver().user_re def set_password_prompt(self, regex = None): """ Defines a pattern that is used to monitor the response of the connected host for a password prompt. @type regex: RegEx @param regex: The pattern that, when matched, causes an error. """ if regex is None: self.manual_password_re = regex else: self.manual_password_re = to_regexs(regex) def get_password_prompt(self): """ Returns the regular expression that is used to monitor the response of the connected host for a username prompt. @rtype: regex @return: A regular expression. """ if self.manual_password_re: return self.manual_password_re return self.get_driver().password_re def set_prompt(self, prompt = None): """ Defines a pattern that is waited for when calling the expect_prompt() method. If the set_prompt() method is not called, or if it is called with the prompt argument set to None, a default prompt is used that should work with many devices running Unix, IOS, IOS-XR, or Junos and others. @type prompt: RegEx @param prompt: The pattern that matches the prompt of the remote host. """ if prompt is None: self.manual_prompt_re = prompt else: self.manual_prompt_re = to_regexs(prompt) def get_prompt(self): """ Returns the regular expressions that is matched against the host response when calling the expect_prompt() method. @rtype: list(re.RegexObject) @return: A list of regular expression objects. """ if self.manual_prompt_re: return self.manual_prompt_re return self.get_driver().prompt_re def set_error_prompt(self, error = None): """ Defines a pattern that is used to monitor the response of the connected host. If the pattern matches (any time the expect() or expect_prompt() methods are used), an error is raised. @type error: RegEx @param error: The pattern that, when matched, causes an error. """ if error is None: self.manual_error_re = error else: self.manual_error_re = to_regexs(error) def get_error_prompt(self): """ Returns the regular expression that is used to monitor the response of the connected host for errors. @rtype: regex @return: A regular expression. """ if self.manual_error_re: return self.manual_error_re return self.get_driver().error_re def set_login_error_prompt(self, error = None): """ Defines a pattern that is used to monitor the response of the connected host during the authentication procedure. If the pattern matches an error is raised. @type error: RegEx @param error: The pattern that, when matched, causes an error. """ if error is None: self.manual_login_error_re = error else: self.manual_login_error_re = to_regexs(error) def get_login_error_prompt(self): """ Returns the regular expression that is used to monitor the response of the connected host for login errors; this is only used during the login procedure, i.e. app_authenticate() or app_authorize(). @rtype: regex @return: A regular expression. """ if self.manual_login_error_re: return self.manual_login_error_re return self.get_driver().login_error_re def set_timeout(self, timeout): """ Defines the maximum time that the adapter waits before a call to L{expect()} or L{expect_prompt()} fails. @type timeout: int @param timeout: The maximum time in seconds. """ self.timeout = int(timeout) def get_timeout(self): """ Returns the current timeout in seconds. @rtype: int @return: The timeout in seconds. """ return self.timeout def _connect_hook(self, host, port): """ Should be overwritten. """ raise NotImplementedError() def connect(self, hostname = None, port = None): """ Opens the connection to the remote host or IP address. @type hostname: string @param hostname: The remote host or IP address. @type port: int @param port: The remote TCP port number. """ if hostname is not None: self.host = hostname return self._connect_hook(self.host, port) def _get_account(self, account): if isinstance(account, Context) or isinstance(account, _Context): return account.context() if account is None: account = self.last_account if self.account_factory: account = self.account_factory(account) else: if account is None: raise TypeError('An account is required') account.__enter__() self.last_account = account return account.context() def login(self, account = None, app_account = None, flush = True): """ Log into the connected host using the best method available. If an account is not given, default to the account that was used during the last call to login(). If a previous call was not made, use the account that was passed to the constructor. If that also fails, raise a TypeError. The app_account is passed to L{app_authenticate()} and L{app_authorize()}. If app_account is not given, default to the value of the account argument. @type account: Account @param account: The account for protocol level authentication. @type app_account: Account @param app_account: The account for app level authentication. @type flush: bool @param flush: Whether to flush the last prompt from the buffer. """ with self._get_account(account) as account: if app_account is None: app_account = account self.authenticate(account, flush = False) if self.get_driver().supports_auto_authorize(): self.expect_prompt() self.auto_app_authorize(app_account, flush = flush) def authenticate(self, account = None, app_account = None, flush = True): """ Like login(), but skips the authorization procedure. @note: If you are unsure whether to use L{authenticate()} or L{login()}, stick with L{login}. @type account: Account @param account: The account for protocol level authentication. @type app_account: Account @param app_account: The account for app level authentication. @type flush: bool @param flush: Whether to flush the last prompt from the buffer. """ with self._get_account(account) as account: if app_account is None: app_account = account self.protocol_authenticate(account) self.app_authenticate(app_account, flush = flush) def _protocol_authenticate(self, user, password): pass def _protocol_authenticate_by_key(self, user, key): pass def protocol_authenticate(self, account = None): """ Low-level API to perform protocol-level authentication on protocols that support it. @note: In most cases, you want to use the login() method instead, as it automatically chooses the best login method for each protocol. @type account: Account @param account: An account object, like login(). """ with self._get_account(account) as account: user = account.get_name() password = account.get_password() key = account.get_key() if key is None: self._dbg(1, "Attempting to authenticate %s." % user) self._protocol_authenticate(user, password) else: self._dbg(1, "Authenticate %s with key." % user) self._protocol_authenticate_by_key(user, key) self.proto_authenticated = True def is_protocol_authenticated(self): """ Returns True if the protocol-level authentication procedure was completed, False otherwise. @rtype: bool @return: Whether the authentication was completed. """ return self.proto_authenticated def _app_authenticate(self, account, password, flush = True, bailout = False): user = account.get_name() while True: # Wait for any prompt. Once a match is found, we need to be able # to find out which type of prompt was matched, so we build a # structure to allow for mapping the match index back to the # prompt type. prompts = (('login-error', self.get_login_error_prompt()), ('username', self.get_username_prompt()), ('skey', [_skey_re]), ('password', self.get_password_prompt()), ('cli', self.get_prompt())) prompt_map = [] prompt_list = [] for section, sectionprompts in prompts: for prompt in sectionprompts: prompt_map.append((section, prompt)) prompt_list.append(prompt) # Wait for the prompt. try: index, match = self._waitfor(prompt_list) except TimeoutException: if self.response is None: self.response = '' msg = "Buffer: %s" % repr(self.response) raise TimeoutException(msg) except DriverReplacedException: # Driver replaced, retry. self._dbg(1, 'Protocol.app_authenticate(): driver replaced') continue except ExpectCancelledException: self._dbg(1, 'Protocol.app_authenticate(): expect cancelled') raise except EOFError: self._dbg(1, 'Protocol.app_authenticate(): EOF') raise # Login error detected. section, prompt = prompt_map[index] if section == 'login-error': raise LoginFailure("Login failed") # User name prompt. elif section == 'username': self._dbg(1, "Username prompt %s received." % index) self.expect(prompt) # consume the prompt from the buffer self.send(user + '\r') continue # s/key prompt. elif section == 'skey': self._dbg(1, "S/Key prompt received.") self.expect(prompt) # consume the prompt from the buffer seq = int(match.group(1)) seed = match.group(2) self.otp_requested_event(account, seq, seed) self._dbg(2, "Seq: %s, Seed: %s" % (seq, seed)) phrase = otp(password, seed, seq) # A password prompt is now required. self.expect(self.get_password_prompt()) self.send(phrase + '\r') self._dbg(1, "Password sent.") if bailout: break continue # Cleartext password prompt. elif section == 'password': self._dbg(1, "Cleartext password prompt received.") self.expect(prompt) # consume the prompt from the buffer self.send(password + '\r') if bailout: break continue # Shell prompt. elif section == 'cli': self._dbg(1, 'Shell prompt received.') if flush: self.expect_prompt() break else: assert False # No such section def app_authenticate(self, account = None, flush = True, bailout = False): """ Attempt to perform application-level authentication. Application level authentication is needed on devices where the username and password are requested from the user after the connection was already accepted by the remote device. The difference between app-level authentication and protocol-level authentication is that in the latter case, the prompting is handled by the client, whereas app-level authentication is handled by the remote device. App-level authentication comes in a large variety of forms, and while this method tries hard to support them all, there is no guarantee that it will always work. We attempt to smartly recognize the user and password prompts; for a list of supported operating systems please check the Exscript.protocols.drivers module. Returns upon finding the first command line prompt. Depending on whether the flush argument is True, it also removes the prompt from the incoming buffer. @type account: Account @param account: An account object, like login(). @type flush: bool @param flush: Whether to flush the last prompt from the buffer. @type bailout: bool @param bailout: Whether to wait for a prompt after sending the password. """ with self._get_account(account) as account: user = account.get_name() password = account.get_password() self._dbg(1, "Attempting to app-authenticate %s." % user) self._app_authenticate(account, password, flush, bailout) self.app_authenticated = True def is_app_authenticated(self): """ Returns True if the application-level authentication procedure was completed, False otherwise. @rtype: bool @return: Whether the authentication was completed. """ return self.app_authenticated def app_authorize(self, account = None, flush = True, bailout = False): """ Like app_authenticate(), but uses the authorization password of the account. For the difference between authentication and authorization please google for AAA. @type account: Account @param account: An account object, like login(). @type flush: bool @param flush: Whether to flush the last prompt from the buffer. @type bailout: bool @param bailout: Whether to wait for a prompt after sending the password. """ with self._get_account(account) as account: user = account.get_name() password = account.get_authorization_password() if password is None: password = account.get_password() self._dbg(1, "Attempting to app-authorize %s." % user) self._app_authenticate(account, password, flush, bailout) self.app_authorized = True def auto_app_authorize(self, account = None, flush = True, bailout = False): """ Like authorize(), but instead of just waiting for a user or password prompt, it automatically initiates the authorization procedure by sending a driver-specific command. In the case of devices that understand AAA, that means sending a command to the device. For example, on routers running Cisco IOS, this command executes the 'enable' command before expecting the password. In the case of a device that is not recognized to support AAA, this method does nothing. @type account: Account @param account: An account object, like login(). @type flush: bool @param flush: Whether to flush the last prompt from the buffer. @type bailout: bool @param bailout: Whether to wait for a prompt after sending the password. """ with self._get_account(account) as account: self._dbg(1, 'Calling driver.auto_authorize().') self.get_driver().auto_authorize(self, account, flush, bailout) def is_app_authorized(self): """ Returns True if the application-level authorization procedure was completed, False otherwise. @rtype: bool @return: Whether the authorization was completed. """ return self.app_authorized def send(self, data): """ Sends the given data to the remote host. Returns without waiting for a response. @type data: string @param data: The data that is sent to the remote host. @rtype: Boolean @return: True on success, False otherwise. """ raise NotImplementedError() def execute(self, command): """ Sends the given data to the remote host (with a newline appended) and waits for a prompt in the response. The prompt attempts to use a sane default that works with many devices running Unix, IOS, IOS-XR, or Junos and others. If that fails, a custom prompt may also be defined using the set_prompt() method. This method also modifies the value of the response (self.response) attribute, for details please see the documentation of the expect() method. @type command: string @param command: The data that is sent to the remote host. @rtype: int, re.MatchObject @return: The index of the prompt regular expression that matched, and the match object. """ self.send(command + '\r') return self.expect_prompt() def _domatch(self, prompt, flush): """ Should be overwritten. """ raise NotImplementedError() def _waitfor(self, prompt): re_list = to_regexs(prompt) patterns = [p.pattern for p in re_list] self._dbg(2, 'waiting for: ' + repr(patterns)) result = self._domatch(re_list, False) return result def waitfor(self, prompt): """ Monitors the data received from the remote host and waits until the response matches the given prompt. Once a match has been found, the buffer containing incoming data is NOT changed. In other words, consecutive calls to this function will always work, e.g.:: conn.waitfor('myprompt>') conn.waitfor('myprompt>') conn.waitfor('myprompt>') will always work. Hence in most cases, you probably want to use expect() instead. This method also stores the received data in the response attribute (self.response). Returns the index of the regular expression that matched. @type prompt: str|re.RegexObject|list(str|re.RegexObject) @param prompt: One or more regular expressions. @rtype: int, re.MatchObject @return: The index of the regular expression that matched, and the match object. @raise TimeoutException: raised if the timeout was reached. @raise ExpectCancelledException: raised when cancel_expect() was called in a callback. @raise ProtocolException: on other internal errors. @raise Exception: May raise other exceptions that are caused within the underlying protocol implementations. """ while True: try: result = self._waitfor(prompt) except DriverReplacedException: continue # retry return result def _expect(self, prompt): result = self._domatch(to_regexs(prompt), True) return result def expect(self, prompt): """ Like waitfor(), but also removes the matched string from the buffer containing the incoming data. In other words, the following may not alway complete:: conn.expect('myprompt>') conn.expect('myprompt>') # timeout Returns the index of the regular expression that matched. @note: May raise the same exceptions as L{waitfor}. @type prompt: str|re.RegexObject|list(str|re.RegexObject) @param prompt: One or more regular expressions. @rtype: int, re.MatchObject @return: The index of the regular expression that matched, and the match object. """ while True: try: result = self._expect(prompt) except DriverReplacedException: continue # retry return result def expect_prompt(self): """ Monitors the data received from the remote host and waits for a prompt in the response. The prompt attempts to use a sane default that works with many devices running Unix, IOS, IOS-XR, or Junos and others. If that fails, a custom prompt may also be defined using the set_prompt() method. This method also stores the received data in the response attribute (self.response). @rtype: int, re.MatchObject @return: The index of the prompt regular expression that matched, and the match object. """ result = self.expect(self.get_prompt()) # We skip the first line because it contains the echo of the command # sent. self._dbg(5, "Checking %s for errors" % repr(self.response)) for line in self.response.split('\n')[1:]: for prompt in self.get_error_prompt(): if not prompt.search(line): continue args = repr(prompt.pattern), repr(line) self._dbg(5, "error prompt (%s) matches %s" % args) raise InvalidCommandException('Device said:\n' + self.response) return result def add_monitor(self, pattern, callback, limit = 80): """ Calls the given function whenever the given pattern matches the incoming data. @note: If you want to catch all incoming data regardless of a pattern, use the L{Protocol.on_data_received} event instead. Arguments passed to the callback are the protocol instance, the index of the match, and the match object of the regular expression. @type pattern: str|re.RegexObject|list(str|re.RegexObject) @param pattern: One or more regular expressions. @type callback: callable @param callback: The function that is called. @type limit: int @param limit: The maximum size of the tail of the buffer that is searched, in number of bytes. """ self.buffer.add_monitor(pattern, partial(callback, self), limit) def cancel_expect(self): """ Cancel the current call to L{expect()} as soon as control returns to the protocol adapter. This method may be used in callbacks to the events emitted by this class, e.g. Protocol.data_received_event. """ raise NotImplementedError() def _call_key_handlers(self, key_handlers, data): if key_handlers is not None: for key, func in key_handlers.iteritems(): if data == key: func(self) return True return False def _set_terminal_size(self, rows, cols): raise NotImplementedError() def _open_posix_shell(self, channel, key_handlers, handle_window_size): # We need to make sure to use an unbuffered stdin, else multi-byte # chars (such as arrow keys) won't work properly. stdin = os.fdopen(sys.stdin.fileno(), 'r', 0) oldtty = termios.tcgetattr(stdin) # Update the terminal size whenever the size changes. if handle_window_size: def handle_sigwinch(signum, frame): rows, cols = get_terminal_size() self._set_terminal_size(rows, cols) signal.signal(signal.SIGWINCH, handle_sigwinch) handle_sigwinch(None, None) # Read from stdin and write to the network, endlessly. try: tty.setraw(sys.stdin.fileno()) tty.setcbreak(sys.stdin.fileno()) channel.settimeout(0.0) while True: try: r, w, e = select.select([channel, stdin], [], []) except select.error, e: code, message = e if code == errno.EINTR: # This may happen when SIGWINCH is called # during the select; we just retry then. continue raise if channel in r: try: data = channel.recv(1024) except socket.timeout: pass if not data: self._dbg(1, 'EOF from remote') break self._receive_cb(data, False) self.buffer.append(data) if stdin in r: data = stdin.read(1) self.buffer.clear() if len(data) == 0: break # Temporarily revert stdin behavior while callbacks are # active. curtty = termios.tcgetattr(stdin) termios.tcsetattr(stdin, termios.TCSADRAIN, oldtty) is_handled = self._call_key_handlers(key_handlers, data) termios.tcsetattr(stdin, termios.TCSADRAIN, curtty) if not is_handled: channel.send(data) finally: termios.tcsetattr(stdin, termios.TCSADRAIN, oldtty) def _open_windows_shell(self, channel, key_handlers): import threading def writeall(sock): while True: data = sock.recv(256) if not data: self._dbg(1, 'EOF from remote') break self._receive_cb(data) writer = threading.Thread(target=writeall, args=(channel,)) writer.start() try: while True: data = sys.stdin.read(1) if not data: break if not self._call_key_handlers(key_handlers, data): channel.send(data) except EOFError: self._dbg(1, 'User hit ^Z or F6') def _open_shell(self, channel, key_handlers, handle_window_size): if _have_termios: return self._open_posix_shell(channel, key_handlers, handle_window_size) else: return self._open_windows_shell(channel, key_handlers, handle_window_size) def interact(self, key_handlers = None, handle_window_size = True): """ Opens a simple interactive shell. Returns when the remote host sends EOF. The optional key handlers are functions that are called whenever the user presses a specific key. For example, to catch CTRL+y:: conn.interact({'\031': mycallback}) @type key_handlers: dict(str: callable) @param key_handlers: A dictionary mapping chars to a functions. @type handle_window_size: bool @param handle_window_size: Whether the connected host is notified when the terminal size changes. """ raise NotImplementedError() def close(self, force = False): """ Closes the connection with the remote host. """ raise NotImplementedError() def get_host(self): """ Returns the name or address of the currently connected host. @rtype: string @return: A name or an address. """ return self.host def guess_os(self): """ Returns an identifier that specifies the operating system that is running on the remote host. This OS is obtained by watching the response of the remote host, such as any messages retrieved during the login procedure. The OS is also a wild guess that often depends on volatile information, so there is no guarantee that this will always work. @rtype: string @return: A string to help identify the remote operating system. """ return self.os_guesser.get('os')
class Protocol(object): """ This is the base class for all protocols; it defines the common portions of the API. The goal of all protocol classes is to provide an interface that is unified across protocols, such that the adapters may be used interchangeably without changing any other code. In order to achieve this, the main challenge are the differences arising from the authentication methods that are used. The reason is that many devices may support the following variety authentication/authorization methods: 1. Protocol level authentication, such as SSH's built-in authentication. - p1: password only - p2: username - p3: username + password - p4: username + key - p5: username + key + password 2. App level authentication, such that the authentication may happen long after a connection is already accepted. This type of authentication is normally used in combination with Telnet, but some SSH hosts also do this (users have reported devices from Enterasys). These devices may also combine protocol-level authentication with app-level authentication. The following types of app-level authentication exist: - a1: password only - a2: username - a3: username + password 3. App level authorization: In order to implement the AAA protocol, some devices ask for two separate app-level logins, whereas the first serves to authenticate the user, and the second serves to authorize him. App-level authorization may support the same methods as app-level authentication: - A1: password only - A2: username - A3: username + password We are assuming that the following methods are used: - Telnet: - p1 - p5: never - a1 - a3: optional - A1 - A3: optional - SSH: - p1 - p5: optional - a1 - a3: optional - A1 - A3: optional To achieve authentication method compatibility across different protocols, we must hide all this complexity behind one single API call, and figure out which ones are supported. As a use-case, our goal is that the following code will always work, regardless of which combination of authentication methods a device supports:: key = PrivateKey.from_file('~/.ssh/id_rsa', 'my_key_password') # The user account to use for protocol level authentication. # The key defaults to None, in which case key authentication is # not attempted. account = Account(name = 'myuser', password = '******', key = key) # The account to use for app-level authentication. # password2 defaults to password. app_account = Account(name = 'myuser', password = '******', password2 = 'my_app_password2') # app_account defaults to account. conn.login(account, app_account = None, flush = True) Another important consideration is that once the login is complete, the device must be in a clearly defined state, i.e. we need to have processed the data that was retrieved from the connected host. More precisely, the buffer that contains the incoming data must be in a state such that the following call to expect_prompt() will either always work, or always fail. We hide the following methods behind the login() call:: # Protocol level authentication. conn.protocol_authenticate(...) # App-level authentication. conn.app_authenticate(...) # App-level authorization. conn.app_authorize(...) The code produces the following result:: Telnet: conn.protocol_authenticate -> NOP conn.app_authenticate -> waits for username or password prompt, authenticates, returns after a CLI prompt was seen. conn.app_authorize -> calls driver.enable(), waits for username or password prompt, authorizes, returns after a CLI prompt was seen. SSH: conn.protocol_authenticate -> authenticates using user/key/password conn.app_authenticate -> like Telnet conn.app_authorize -> like Telnet We can see the following: - protocol_authenticate() must not wait for a prompt, because else app_authenticate() has no way of knowing whether an app-level login is even necessary. - app_authenticate() must check the buffer first, to see if authentication has already succeeded. In the case that app_authenticate() is not necessary (i.e. the buffer contains a CLI prompt), it just returns. app_authenticate() must NOT eat the prompt from the buffer, because else the result may be inconsistent with devices that do not do any authentication; i.e., when app_authenticate() is not called. - Since the prompt must still be contained in the buffer, conn.driver.app_authorize() needs to eat it before it sends the command for starting the authorization procedure. This has a drawback - if a user attempts to call app_authorize() at a time where there is no prompt in the buffer, it would fail. So we need to eat the prompt only in cases where we know that auto_app_authorize() will attempt to execute a command. Hence the driver requires the Driver.supports_auto_authorize() method. However, app_authorize() must not eat the CLI prompt that follows. - Once all logins are processed, it makes sense to eat the prompt depending on the wait parameter. Wait should default to True, because it's better that the connection stalls waiting forever, than to risk that an error is not immediately discovered due to timing issues (this is a race condition that I'm not going to detail here). """ def __init__(self, driver=None, stdout=None, stderr=None, debug=0, connect_timeout=30, timeout=30, logfile=None, termtype='dumb', verify_fingerprint=True, account_factory=None): """ Constructor. The following events are provided: - data_received_event: A packet was received from the connected host. - otp_requested_event: The connected host requested a one-time-password to be entered. :keyword driver: Driver()|str :keyword stdout: Where to write the device response. Defaults to os.devnull. :keyword stderr: Where to write debug info. Defaults to stderr. :keyword debug: An integer between 0 (no debugging) and 5 (very verbose debugging) that specifies the amount of debug info sent to the terminal. The default value is 0. :keyword connect_timeout: Timeout for the initial TCP connection attempt :keyword timeout: See set_timeout(). The default value is 30. :keyword logfile: A file into which a log of the conversation with the device is dumped. :keyword termtype: The terminal type to request from the remote host, e.g. 'vt100'. :keyword verify_fingerprint: Whether to verify the host's fingerprint. :keyword account_factory: A function that produces a new :class:`Account`. """ self.data_received_event = Event() self.otp_requested_event = Event() self.os_guesser = OsGuesser() self.auto_driver = driver_map[self.guess_os()] self.proto_authenticated = False self.app_authenticated = False self.app_authorized = False self.manual_user_re = None self.manual_password_re = None self.manual_prompt_re = None self.manual_error_re = None self.manual_login_error_re = None self.driver_replaced = False self.host = None self.port = None self.last_account = None self.termtype = termtype self.verify_fingerprint = verify_fingerprint self.manual_driver = None self.debug = debug self.connect_timeout = connect_timeout self.timeout = timeout self.logfile = logfile self.response = None self.buffer = MonitoredBuffer() self.account_factory = account_factory self.send_data = None if stdout is None: self.stdout = open(os.devnull, 'w') else: self.stdout = stdout if stderr is None: self.stderr = sys.stderr else: self.stderr = stderr if logfile is None: self.log = None else: self.log = open(logfile, 'a') # set manual_driver if driver is not None: if isinstance(driver, str): if driver in driver_map: self.manual_driver = driver_map[driver] else: self._dbg(1, 'Invalid driver string given. Ignoring...') elif isinstance(driver, Driver): self.manual_driver = driver else: self._dbg(1, 'Invalid driver given. Ignoring...') def __copy__(self): """ Overwritten to return the very same object instead of copying the stream, because copying a network connection is impossible. :rtype: Protocol :return: self """ return self def __deepcopy__(self, memo): """ Overwritten to return the very same object instead of copying the stream, because copying a network connection is impossible. :type memo: object :param memo: Please refer to Python's standard library documentation. :rtype: Protocol :return: self """ return self def _driver_replaced_notify(self, old, new): self.driver_replaced = True self.cancel_expect() msg = 'Protocol: driver replaced: %s -> %s' % (old.name, new.name) self._dbg(1, msg) def _receive_cb(self, data, remove_cr=True): # Clean the data up. if remove_cr: text = data.replace('\r', '') else: text = data # Write to a logfile. self.stdout.write(text) self.stdout.flush() if self.log is not None: self.log.write(text) # Check whether a better driver is found based on the incoming data. old_driver = self.get_driver() self.os_guesser.data_received(data, self.is_app_authenticated()) self.auto_driver = driver_map[self.guess_os()] new_driver = self.get_driver() if old_driver != new_driver: self._driver_replaced_notify(old_driver, new_driver) # Send signals to subscribers. self.data_received_event(data) def is_dummy(self): """ Returns True if the adapter implements a virtual device, i.e. it isn't an actual network connection. :rtype: Boolean :return: True for dummy adapters, False for network adapters. """ return False def _dbg(self, level, msg): if self.debug < level: return self.stderr.write(self.get_driver().name + ': ' + msg + '\n') def set_driver(self, driver=None): """ Defines the driver that is used to recognize prompts and implement behavior depending on the remote system. The driver argument may be an instance of a protocols.drivers.Driver subclass, a known driver name (string), or None. If the driver argument is None, the adapter automatically chooses a driver using the guess_os() function. :type driver: Driver()|str :param driver: The pattern that, when matched, causes an error. """ if driver is None: self.manual_driver = None elif isinstance(driver, str): if driver not in driver_map: raise TypeError('no such driver:' + repr(driver)) self.manual_driver = driver_map[driver] elif isinstance(driver, Driver): self.manual_driver = driver else: raise TypeError('unsupported argument type:' + type(driver)) def get_driver(self): """ Returns the currently used driver. :rtype: Driver :return: A regular expression. """ if self.manual_driver: return self.manual_driver return self.auto_driver def autoinit(self): """ Make the remote host more script-friendly by automatically executing one or more commands on it. The commands executed depend on the currently used driver. For example, the driver for Cisco IOS would execute the following commands:: term len 0 term width 0 """ self.get_driver().init_terminal(self) def set_username_prompt(self, regex=None): """ Defines a pattern that is used to monitor the response of the connected host for a username prompt. :type regex: RegEx :param regex: The pattern that, when matched, causes an error. """ if regex is None: self.manual_user_re = regex else: self.manual_user_re = to_regexs(regex) def get_username_prompt(self): """ Returns the regular expression that is used to monitor the response of the connected host for a username prompt. :rtype: regex :return: A regular expression. """ if self.manual_user_re: return self.manual_user_re return self.get_driver().user_re def set_password_prompt(self, regex=None): """ Defines a pattern that is used to monitor the response of the connected host for a password prompt. :type regex: RegEx :param regex: The pattern that, when matched, causes an error. """ if regex is None: self.manual_password_re = regex else: self.manual_password_re = to_regexs(regex) def get_password_prompt(self): """ Returns the regular expression that is used to monitor the response of the connected host for a username prompt. :rtype: regex :return: A regular expression. """ if self.manual_password_re: return self.manual_password_re return self.get_driver().password_re def set_prompt(self, prompt=None): """ Defines a pattern that is waited for when calling the expect_prompt() method. If the set_prompt() method is not called, or if it is called with the prompt argument set to None, a default prompt is used that should work with many devices running Unix, IOS, IOS-XR, or Junos and others. :type prompt: RegEx :param prompt: The pattern that matches the prompt of the remote host. """ if prompt is None: self.manual_prompt_re = prompt else: self.manual_prompt_re = to_regexs(prompt) def get_prompt(self): """ Returns the regular expressions that is matched against the host response when calling the expect_prompt() method. :rtype: list(re.RegexObject) :return: A list of regular expression objects. """ if self.manual_prompt_re: return self.manual_prompt_re return self.get_driver().prompt_re def set_error_prompt(self, error=None): """ Defines a pattern that is used to monitor the response of the connected host. If the pattern matches (any time the expect() or expect_prompt() methods are used), an error is raised. :type error: RegEx :param error: The pattern that, when matched, causes an error. """ if error is None: self.manual_error_re = error else: self.manual_error_re = to_regexs(error) def get_error_prompt(self): """ Returns the regular expression that is used to monitor the response of the connected host for errors. :rtype: regex :return: A regular expression. """ if self.manual_error_re: return self.manual_error_re return self.get_driver().error_re def set_login_error_prompt(self, error=None): """ Defines a pattern that is used to monitor the response of the connected host during the authentication procedure. If the pattern matches an error is raised. :type error: RegEx :param error: The pattern that, when matched, causes an error. """ if error is None: self.manual_login_error_re = error else: self.manual_login_error_re = to_regexs(error) def get_login_error_prompt(self): """ Returns the regular expression that is used to monitor the response of the connected host for login errors; this is only used during the login procedure, i.e. app_authenticate() or app_authorize(). :rtype: regex :return: A regular expression. """ if self.manual_login_error_re: return self.manual_login_error_re return self.get_driver().login_error_re def set_connect_timeout(self, timeout): """ Defines the maximum time that the adapter waits for initial connection. :type timeout: int :param timeout: The maximum time in seconds. """ self.connect_timeout = int(timeout) def get_connect_timeout(self): """ Returns the current connect_timeout in seconds. :rtype: int :return: The connect_timeout in seconds. """ return self.connect_timeout def set_timeout(self, timeout): """ Defines the maximum time that the adapter waits before a call to :class:`expect()` or :class:`expect_prompt()` fails. :type timeout: int :param timeout: The maximum time in seconds. """ self.timeout = int(timeout) def get_timeout(self): """ Returns the current timeout in seconds. :rtype: int :return: The timeout in seconds. """ return self.timeout def _connect_hook(self, host, port): """ Should be overwritten. """ raise NotImplementedError() def connect(self, hostname=None, port=None): """ Opens the connection to the remote host or IP address. :type hostname: string :param hostname: The remote host or IP address. :type port: int :param port: The remote TCP port number. """ if hostname is not None: self.host = hostname return self._connect_hook(self.host, port) def _get_account(self, account): if isinstance(account, Context) or isinstance(account, _Context): return account.context() if account is None: account = self.last_account if self.account_factory: account = self.account_factory(account) else: if account is None: raise TypeError('An account is required') account.__enter__() self.last_account = account return account.context() def login(self, account=None, app_account=None, flush=True): """ Log into the connected host using the best method available. If an account is not given, default to the account that was used during the last call to login(). If a previous call was not made, use the account that was passed to the constructor. If that also fails, raise a TypeError. The app_account is passed to :class:`app_authenticate()` and :class:`app_authorize()`. If app_account is not given, default to the value of the account argument. :type account: Account :param account: The account for protocol level authentication. :type app_account: Account :param app_account: The account for app level authentication. :type flush: bool :param flush: Whether to flush the last prompt from the buffer. """ with self._get_account(account) as account: if app_account is None: app_account = account self.authenticate(account, flush=False) if self.get_driver().supports_auto_authorize(): self.expect_prompt() self.auto_app_authorize(app_account, flush=flush) def authenticate(self, account=None, app_account=None, flush=True): """ Like login(), but skips the authorization procedure. .. HINT:: If you are unsure whether to use :class:`authenticate()` or :class:`login()`, stick with :class:`login`. :type account: Account :param account: The account for protocol level authentication. :type app_account: Account :param app_account: The account for app level authentication. :type flush: bool :param flush: Whether to flush the last prompt from the buffer. """ with self._get_account(account) as account: if app_account is None: app_account = account self.protocol_authenticate(account) self.app_authenticate(app_account, flush=flush) def _protocol_authenticate(self, user, password): pass def _protocol_authenticate_by_key(self, user, key): pass def protocol_authenticate(self, account=None): """ Low-level API to perform protocol-level authentication on protocols that support it. .. HINT:: In most cases, you want to use the login() method instead, as it automatically chooses the best login method for each protocol. :type account: Account :param account: An account object, like login(). """ with self._get_account(account) as account: user = account.get_name() password = account.get_password() key = account.get_key() if key is None: self._dbg(1, "Attempting to authenticate %s." % user) self._protocol_authenticate(user, password) else: self._dbg(1, "Authenticate %s with key." % user) self._protocol_authenticate_by_key(user, key) self.proto_authenticated = True def is_protocol_authenticated(self): """ Returns True if the protocol-level authentication procedure was completed, False otherwise. :rtype: bool :return: Whether the authentication was completed. """ return self.proto_authenticated def _app_authenticate(self, account, password, flush=True, bailout=False): user = account.get_name() while True: # Wait for any prompt. Once a match is found, we need to be able # to find out which type of prompt was matched, so we build a # structure to allow for mapping the match index back to the # prompt type. prompts = (('login-error', self.get_login_error_prompt()), ('username', self.get_username_prompt()), ('skey', [_skey_re]), ('password', self.get_password_prompt()), ('cli', self.get_prompt())) prompt_map = [] prompt_list = [] for section, sectionprompts in prompts: for prompt in sectionprompts: prompt_map.append((section, prompt)) prompt_list.append(prompt) # Wait for the prompt. try: index, match = self._waitfor(prompt_list) except TimeoutException: if self.response is None: self.response = '' msg = "Buffer: %s" % repr(self.response) raise TimeoutException(msg) except DriverReplacedException: # Driver replaced, retry. self._dbg(1, 'Protocol.app_authenticate(): driver replaced') continue except ExpectCancelledException: self._dbg(1, 'Protocol.app_authenticate(): expect cancelled') raise except EOFError: self._dbg(1, 'Protocol.app_authenticate(): EOF') raise # Login error detected. section, prompt = prompt_map[index] if section == 'login-error': raise LoginFailure("Login failed") # User name prompt. elif section == 'username': self._dbg(1, "Username prompt %s received." % index) self.expect(prompt) # consume the prompt from the buffer self.send(user + '\r') continue # s/key prompt. elif section == 'skey': self._dbg(1, "S/Key prompt received.") self.expect(prompt) # consume the prompt from the buffer seq = int(match.group(1)) seed = match.group(2) self.otp_requested_event(account, seq, seed) self._dbg(2, "Seq: %s, Seed: %s" % (seq, seed)) phrase = otp(password, seed, seq) # A password prompt is now required. self.expect(self.get_password_prompt()) self.send(phrase + '\r') self._dbg(1, "Password sent.") if bailout: break continue # Cleartext password prompt. elif section == 'password': self._dbg(1, "Cleartext password prompt received.") self.expect(prompt) # consume the prompt from the buffer self.send(password + '\r') if bailout: break continue # Shell prompt. elif section == 'cli': self._dbg(1, 'Shell prompt received.') if flush: self.expect_prompt() break else: assert False # No such section def app_authenticate(self, account=None, flush=True, bailout=False): """ Attempt to perform application-level authentication. Application level authentication is needed on devices where the username and password are requested from the user after the connection was already accepted by the remote device. The difference between app-level authentication and protocol-level authentication is that in the latter case, the prompting is handled by the client, whereas app-level authentication is handled by the remote device. App-level authentication comes in a large variety of forms, and while this method tries hard to support them all, there is no guarantee that it will always work. We attempt to smartly recognize the user and password prompts; for a list of supported operating systems please check the Exscript.protocols.drivers module. Returns upon finding the first command line prompt. Depending on whether the flush argument is True, it also removes the prompt from the incoming buffer. :type account: Account :param account: An account object, like login(). :type flush: bool :param flush: Whether to flush the last prompt from the buffer. :type bailout: bool :param bailout: Whether to wait for a prompt after sending the password. """ with self._get_account(account) as account: user = account.get_name() password = account.get_password() self._dbg(1, "Attempting to app-authenticate %s." % user) self._app_authenticate(account, password, flush, bailout) self.app_authenticated = True def is_app_authenticated(self): """ Returns True if the application-level authentication procedure was completed, False otherwise. :rtype: bool :return: Whether the authentication was completed. """ return self.app_authenticated def app_authorize(self, account=None, flush=True, bailout=False): """ Like app_authenticate(), but uses the authorization password of the account. For the difference between authentication and authorization please google for AAA. :type account: Account :param account: An account object, like login(). :type flush: bool :param flush: Whether to flush the last prompt from the buffer. :type bailout: bool :param bailout: Whether to wait for a prompt after sending the password. """ with self._get_account(account) as account: user = account.get_name() password = account.get_authorization_password() if password is None: password = account.get_password() self._dbg(1, "Attempting to app-authorize %s." % user) self._app_authenticate(account, password, flush, bailout) self.app_authorized = True def auto_app_authorize(self, account=None, flush=True, bailout=False): """ Like authorize(), but instead of just waiting for a user or password prompt, it automatically initiates the authorization procedure by sending a driver-specific command. In the case of devices that understand AAA, that means sending a command to the device. For example, on routers running Cisco IOS, this command executes the 'enable' command before expecting the password. In the case of a device that is not recognized to support AAA, this method does nothing. :type account: Account :param account: An account object, like login(). :type flush: bool :param flush: Whether to flush the last prompt from the buffer. :type bailout: bool :param bailout: Whether to wait for a prompt after sending the password. """ with self._get_account(account) as account: self._dbg(1, 'Calling driver.auto_authorize().') self.get_driver().auto_authorize(self, account, flush, bailout) def is_app_authorized(self): """ Returns True if the application-level authorization procedure was completed, False otherwise. :rtype: bool :return: Whether the authorization was completed. """ return self.app_authorized def send(self, data): """ Sends the given data to the remote host. Returns without waiting for a response. :type data: string :param data: The data that is sent to the remote host. :rtype: Boolean :return: True on success, False otherwise. """ raise NotImplementedError() def execute(self, command, consume=True): """ Sends the given data to the remote host (with a newline appended) and waits for a prompt in the response. The prompt attempts to use a sane default that works with many devices running Unix, IOS, IOS-XR, or Junos and others. If that fails, a custom prompt may also be defined using the set_prompt() method. This method also modifies the value of the response (self.response) attribute, for details please see the documentation of the expect() method. :type command: string :param command: The data that is sent to the remote host. :type consume: boolean (Default: True) :param consume: Whether to consume the prompt from the buffer or not. :rtype: int, re.MatchObject :return: The index of the prompt regular expression that matched, and the match object. """ self.send(command + '\r') return self.expect_prompt(consume) def _domatch(self, prompt, flush): """ Should be overwritten. """ raise NotImplementedError() def _waitfor(self, prompt): re_list = to_regexs(prompt) patterns = [p.pattern for p in re_list] self._dbg(2, 'waiting for: ' + repr(patterns)) result = self._domatch(re_list, False) return result def waitfor(self, prompt): """ Monitors the data received from the remote host and waits until the response matches the given prompt. Once a match has been found, the buffer containing incoming data is NOT changed. In other words, consecutive calls to this function will always work, e.g.:: conn.waitfor('myprompt>') conn.waitfor('myprompt>') conn.waitfor('myprompt>') will always work. Hence in most cases, you probably want to use expect() instead. This method also stores the received data in the response attribute (self.response). Returns the index of the regular expression that matched. :type prompt: str|re.RegexObject|list(str|re.RegexObject) :param prompt: One or more regular expressions. :rtype: int, re.MatchObject :return: The index of the regular expression that matched, and the match object. @raise TimeoutException: raised if the timeout was reached. @raise ExpectCancelledException: raised when cancel_expect() was called in a callback. @raise ProtocolException: on other internal errors. @raise Exception: May raise other exceptions that are caused within the underlying protocol implementations. """ while True: try: result = self._waitfor(prompt) except DriverReplacedException: continue # retry return result def _expect(self, prompt): result = self._domatch(to_regexs(prompt), True) return result def expect(self, prompt): """ Like waitfor(), but also removes the matched string from the buffer containing the incoming data. In other words, the following may not alway complete:: conn.expect('myprompt>') conn.expect('myprompt>') # timeout Returns the index of the regular expression that matched. .. HINT:: May raise the same exceptions as :class:`waitfor`. :type prompt: str|re.RegexObject|list(str|re.RegexObject) :param prompt: One or more regular expressions. :rtype: int, re.MatchObject :return: The index of the regular expression that matched, and the match object. """ while True: try: result = self._expect(prompt) except DriverReplacedException: continue # retry return result def expect_prompt(self, consume=True): """ Monitors the data received from the remote host and waits for a prompt in the response. The prompt attempts to use a sane default that works with many devices running Unix, IOS, IOS-XR, or Junos and others. If that fails, a custom prompt may also be defined using the set_prompt() method. This method also stores the received data in the response attribute (self.response). :type consume: boolean (Default: True) :param consume: Whether to consume the prompt from the buffer or not. :rtype: int, re.MatchObject :return: The index of the prompt regular expression that matched, and the match object. """ if consume: result = self.expect(self.get_prompt()) else: self._dbg(1, "DO NOT CONSUME PROMPT!") result = self.waitfor(self.get_prompt()) # We skip the first line because it contains the echo of the command # sent. self._dbg(5, "Checking %s for errors" % repr(self.response)) for line in self.response.split('\n')[1:]: for prompt in self.get_error_prompt(): if not prompt.search(line): continue args = repr(prompt.pattern), repr(line) self._dbg(5, "error prompt (%s) matches %s" % args) raise InvalidCommandException('Device said:\n' + self.response) return result def add_monitor(self, pattern, callback, limit=80): """ Calls the given function whenever the given pattern matches the incoming data. .. HINT:: If you want to catch all incoming data regardless of a pattern, use the Protocol.data_received_event event instead. Arguments passed to the callback are the protocol instance, the index of the match, and the match object of the regular expression. :type pattern: str|re.RegexObject|list(str|re.RegexObject) :param pattern: One or more regular expressions. :type callback: callable :param callback: The function that is called. :type limit: int :param limit: The maximum size of the tail of the buffer that is searched, in number of bytes. """ self.buffer.add_monitor(pattern, partial(callback, self), limit) def cancel_expect(self): """ Cancel the current call to :class:`expect()` as soon as control returns to the protocol adapter. This method may be used in callbacks to the events emitted by this class, e.g. Protocol.data_received_event. """ raise NotImplementedError() def _call_key_handlers(self, key_handlers, data): if key_handlers is not None: for key, func in key_handlers.iteritems(): if data == key: func(self) return True return False def _set_terminal_size(self, rows, cols): raise NotImplementedError() def _open_posix_shell(self, channel, key_handlers, handle_window_size): # We need to make sure to use an unbuffered stdin, else multi-byte # chars (such as arrow keys) won't work properly. stdin = os.fdopen(sys.stdin.fileno(), 'r', 0) oldtty = termios.tcgetattr(stdin) # Update the terminal size whenever the size changes. if handle_window_size: def handle_sigwinch(signum, frame): rows, cols = get_terminal_size() self._set_terminal_size(rows, cols) signal.signal(signal.SIGWINCH, handle_sigwinch) handle_sigwinch(None, None) # Read from stdin and write to the network, endlessly. try: tty.setraw(sys.stdin.fileno()) tty.setcbreak(sys.stdin.fileno()) channel.settimeout(0.0) while True: try: r, w, e = select.select([channel, stdin], [], []) except select.error, e: code, message = e if code == errno.EINTR: # This may happen when SIGWINCH is called # during the select; we just retry then. continue raise if channel in r: try: data = channel.recv(1024) except socket.timeout: pass if not data: self._dbg(1, 'EOF from remote') break self._receive_cb(data, False) self.buffer.append(data) if stdin in r: data = stdin.read(1) self.buffer.clear() if len(data) == 0: break # Temporarily revert stdin behavior while callbacks are # active. curtty = termios.tcgetattr(stdin) termios.tcsetattr(stdin, termios.TCSADRAIN, oldtty) is_handled = self._call_key_handlers(key_handlers, data) termios.tcsetattr(stdin, termios.TCSADRAIN, curtty) if not is_handled: if not self.send_data is None: self.send_data.write(data) channel.send(data) finally: termios.tcsetattr(stdin, termios.TCSADRAIN, oldtty) def _open_windows_shell(self, channel, key_handlers): import threading def writeall(sock): while True: data = sock.recv(256) if not data: self._dbg(1, 'EOF from remote') break self._receive_cb(data) writer = threading.Thread(target=writeall, args=(channel, )) writer.start() try: while True: data = sys.stdin.read(1) if not data: break if not self._call_key_handlers(key_handlers, data): if not self.send_data is None: self.send_data.write(data) channel.send(data) except EOFError: self._dbg(1, 'User hit ^Z or F6') def _open_shell(self, channel, key_handlers, handle_window_size): if _have_termios: return self._open_posix_shell(channel, key_handlers, handle_window_size) else: return self._open_windows_shell(channel, key_handlers, handle_window_size) def interact(self, key_handlers=None, handle_window_size=True): """ Opens a simple interactive shell. Returns when the remote host sends EOF. The optional key handlers are functions that are called whenever the user presses a specific key. For example, to catch CTRL+y:: conn.interact({'\031': mycallback}) :type key_handlers: dict(str: callable) :param key_handlers: A dictionary mapping chars to a functions. :type handle_window_size: bool :param handle_window_size: Whether the connected host is notified when the terminal size changes. """ raise NotImplementedError() def close(self, force=False): """ Closes the connection with the remote host. """ raise NotImplementedError() def get_host(self): """ Returns the name or address of the currently connected host. :rtype: string :return: A name or an address. """ return self.host def guess_os(self): """ Returns an identifier that specifies the operating system that is running on the remote host. This OS is obtained by watching the response of the remote host, such as any messages retrieved during the login procedure. The OS is also a wild guess that often depends on volatile information, so there is no guarantee that this will always work. :rtype: string :return: A string to help identify the remote operating system. """ return self.os_guesser.get('os')