State

The State object tracks several variables for a single instance of the Handler.

As seen in the following example, you can create a State variable externally and control it there. In the event that you do not pass in a State, one is created automatically. You can also continue to manipulate the State in the ways shown below.

#!/usr/bin/env python3

import synack

state = synack.State()
state.debug = True
handler = synack.Handler(state)
handler.debug.log("Test", "This message WILL be seen")
handler.state.debug = False
handler.debug.log("Test", "This message will NOT be seen")
state = True
handler.debug.log("Test", "This message WILL be seen")

# ----- OR -----

handler = synack.Handler(debug=True)
handler.debug.log("Test", "This message WILL be seen")
handler.state.debug = False
handler.debug.log("Test", "This message will NOT be seen")
handler.state.debug = True
handler.debug.log("Test", "This message WILL be seen")

Out of all of the State variables, login is the most important to understand. If this is set to true, whenever your Handler is created, it will make sure you are logged in. If you have a bunch of scripts based on SynackAPI, it is probably a good idea to have login set to False, which is the default, for the majority of scripts. Then you can have a couple scripts which are run periodically with login set to True so it becomes responsible for making sure that everything is logged in.

As an example of a good function to set login to True, check out the Register Targets Example.

Database vs State

The observant will notice that there is a lot of overlap between the values stored in the Database and the State. This may cause you some confusion as to where data is coming from and how it's being stored and accessed.

The Database contains persistent or shared information. For example, the api_token, which should be shared by all Handlers or cached Target information that could be quickly referenced.

The State only persists within one instance of the Handler. In the event that one of the State variables is set and is not constantly at risk of being changed (such as the api_token), the value stored in the State will be provided instead of the Database value. This is useful when you want to override Database variables in a single Handler. For example, you may wish to enable the debug variable for a single Handler without affecting other Handlers you may have running.

Variables