Saram’s documentation¶

This is the documentation for saramPy, the Python interface for the Saram API.

Usage¶

saramPy uses two tokens to communicate with the Saram server. One of them is the API token, and one of them is the entry token. Although both of the tokens are required, the API token can be read from a local config file. This config file is in JSON format and contains the API key and the username associated with that API key. This config file can be set up in two ways:

Python¶

from saramPy import SaramInit
s = SaramInit(api_key='yourApiKey')
s.init()

Command line¶

saramPy --init yourApiKey [--base_url] [--local]
# Set --local to set self hosted solution, or --base_url if using anything other than the main app

saramPy docs¶

Command line tool¶

`saramPy` will install a handy command line tool that ties around the most commonly used methods and send them to the server.

usage: saramPy [-h] -t TOKEN [--comment COMMENT] [-c ... | -f FILE]

optional arguments:
-h, --help            show this help message and exit
-t TOKEN, --token TOKEN
                        Token for the entry
--comment COMMENT     Add an optional comment
-c ..., --command ...
                        Command to run inside quotes
-f FILE, --file FILE  Read a file and send it to the server

Python module¶

`saramPy` exposes two main classes with distinct use cases.

saramPy.Saram¶

This class exposes the most helpful classes and is typically used for:

sending script output

sending command output

sending code examples

class saramPy.Saram(token: str)¶

The Saram class. If FileNotFound excetption, then the .saram.conf file is missing. Init it correctly.

>>> # import and instantiate Saram
>>> from saramPy import Saram
>>> s = Saram(token='token value', user='username')

Parameters:	token (str) – Token for the Entry/URL.
Returns:	Saram object
Return type:	object

file_content(file_path: str, comment: Optional[str] = None, file_name: Optional[str] = None) → saramPy.Saram¶

Reads the content of the provided files path. Optional parameters are comment and file_name.

Parameters:	file_path (str) – File path comment (str) – Optional make a comment file_name (str) – File path
Returns:	Saram object
Return type:	object

>>> s.file_content('/path/to/file.extension').send() # send the content to the server

run_command(command: str, comment: Optional[str] = None) → saramPy.Saram¶

Runs the command and gets the output of stdout. Does not support bash one liners or too many piped outputs. In those cases, write the command to a file, and send the content of the file instead with `file_content`. Optional params are `comment`.

Parameters:	command (str) – Command to run. Could be string or an array comment (str) – Optional make a comment
Returns:	Saram object. Access with `command_output` attribute
Return type:	self

>>> s.run_command('ls -l /tmp/', comment='Output of ls')
>>> s.send()

script_dump(script_name: Optional[str] = None, comment=None) → saramPy.Saram¶

Reads a file till the point this method is called. Can be used as many times as needed.

Parameters:	script_name (str) – Optional name of the script being read comment (str) – Optional make a comment
Returns:	Saram object
Return type:	object

script_read_self(comment: Optional[str] = None, script_name: Optional[str] = None) → saramPy.Saram¶

Read the contents of the file that this function is called in and return the whole content. Optional parameters are `comment` and `script` name.

Parameters:	comment (str) – Optional make a comment script_name (str) – Optional name of the script being read
Returns:	Returns Saram object. Access with `output` attribute
Return type:	str

>>> s.script_read_self(script_name="solver.py", comment="Solve pwn challenge")
>>> s.send() # send the content to the server

send_to_server() → requests.models.Response¶

Sends a dict object to the server to save. Will print OK or 200 status code on success.

>>> s.run_command(command).send_to_server()

Returns:	response from request. access with `response` attribute
Return type:	requests.Response

variable_output(var: any, comment: Optional[str] = None, script_name: Optional[str] = None) → saramPy.Saram¶

Send any data like the output of a python script to the server. This is useful when only the output of a particular variable needs to the sent to the sever, and not the whole script itself. Optional parameters are comment and script_name.

Parameters:	var (any) – Variable comment (str) – Optional make a comment script_name (any) – Variable
Returns:	Saram object
Return type:	object

>>> # set data to a variable
>>> response = request.get('https://google.com').text
>>> # Send data to the server
>>> s.variable_output(response).send()

saramPy.api.SaramAPI¶

This class exports the full functionality of the Saram API and can be use to build tools and integrations around.

API docs

class saramPy.api.SaramAPI¶

Class that exposes the full API for Saram. Interits from saramPy.Saram. This class reads from the local .saram.conf file to instialize many of its properties.

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()

addComment(token: str, dataid: str, comment: str) → dict¶

Add a comment to a section.

Parameters:	token (str) – Valid token for the entry dataid (str) – Valid section to add the comment to comment (str) – Comment to add
Raises:	StatusNotOk – Exception on fail
Returns:	OK object
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.addComment(
>>>     token='080d33e0-demo-title',
>>>     dataid='bfe02810-656d-11e9-be3a-05d3364ece32',
>>>     comment='Additional comment'
>>> )
>>> print(s)

adminAllUsers() → list¶

Get an array of all user objects

Raises:	StatusNotOk – Exception
Returns:	Array of user objects
Return type:	list

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.adminAllUsers()
>>> print(s)

adminCreateUser(username: str, password: str, isAdmin: bool = False, avatar: str = '/static/logo.png') → dict¶

Create a new user

Parameters:	username (str) – A valid username. Spaces and special characters are stripped password (str) – A password. Password is stored as a hash isAdmin – True if the user is an admin, defaults to False isAdmin – bool, optional avatar – A link to the profile image for the user, defaults to ‘/static/logo.png’ avatar – str, optional
Raises:	StatusNotOk – Exception
Returns:	A complete user object
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.adminCreateUser(
>>>     username='someUserName',
>>>     password='someSecretPassword',
>>>     isAdmin=False,
>>>     avatar='http://pstu.ac.bd/images/defaults/default.png'
>>> )
>>> print(s)

adminDeleteLogs() → list¶

Delete all logs

Raises:	StatusNotOk – Exception
Returns:	OK object
Return type:	object

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.adminDeleteLogs()
>>> print(s)

adminDeleteUser(user_id: str) → dict¶

Delete a user by user id

Parameters:	user_id (str) – A valid user id
Raises:	StatusNotOk – Exception
Returns:	True if deleted
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.adminDeleteUser(
>>>     user_id='5cbf14d11beae8c5e3bdc695'
>>> )
>>> print(s)

adminDestroyDB(confirm: bool) → dict¶

Destroy the Saram db. This does not destroy the user or session dbs.

Parameters:	confirm – Confirm
Raises:	StatusNotOk – Exception
Returns:	reponse dictionary object
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.adminDestroyDB(
>>>     confirm=True
>>> )
>>> print(s)

adminFindUser(user_id: str) → dict¶

Find a user by user id

Parameters:	user_id (str) – A valid user id
Raises:	StatusNotOk – Exception
Returns:	A complete user object
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.adminFindUser('1')
>>> print(s)

adminGetLogs() → list¶

Get an arry of all the log objects

Raises:	StatusNotOk – Exception
Returns:	Array of log objects
Return type:	list

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.adminGetLogs()
>>> print(s)

adminGetSentryErrors() → list¶

Get an array of all unresolved errors in Sentry if enabled

Raises:	StatusNotOk – Exception
Returns:	Array of log objects
Return type:	list

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.adminGetSentryErrors()
>>> print(s)

adminGetStatus() → list¶

Gets the server status as an array of objects

Raises:	StatusNotOk – Exception
Returns:	Array of log objects
Return type:	list

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.adminGetStatus()
>>> print(s)

adminUpdateUser(user_id: str, **kwargs) → dict¶

Update a users information. Any valid user field can be updated using this method.

Parameters:	username (str, optional) – New username to change to isAdmin – Toggle ‘true’ or ‘false’ isAdmin – bool, optional isDisabled – Toggle ‘true’ or ‘false’ isDisabled – bool, optional avatar – A link to the profile image for the user, defaults to ‘/static/logo.png’ avatar – str, optional
Raises:	StatusNotOk – Exception
Returns:	A complete user object
Return type:	dict

>>> # This example shows how to change the admin status of a user
>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.adminUpdateUser(
>>>     user_id='2',
>>>     isAdmin='false',
>>>     isDisabled='false'
>>> )
>>> print(s)

changeAvatar(avatar: str) → dict¶

Change the username to a new username

Parameters:	avatar (str) – Valid avatar url. Only built in avatars are allowed. A valid url is `/static/avatar/[1-20].png`
Raises:	StatusNotOk – Exception on fail
Returns:	object with both old and new usernames
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.changeAvatar(
>>>     avatar='/static/avatar/2.png'
>>> )
>>> print(s)

changeUsername(api_key: str, old_username: str, new_username: str) → dict¶

Change the username to a new username

Parameters:	api_key (str) – Valid API key old_username (str) – Old username new_username (str) – New username
Raises:	StatusNotOk – Exception on fail
Returns:	object with both old and new usernames
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.changeUsername(
>>>     api_key='secretApiKey',
>>>     old_username='oldUserName',
>>>     new_username='newUserName'
>>> )
>>> print(s)

createNewEntry(title: str, category: str) → dict¶

Create a new entry. This is a whole new entry to work with

Parameters:	title (str) – Title of section/challenge category (str) – Category of section/challenge
Raises:	NotValidCategory – Exception if a vategory is not valid StatusNotOk – Exception on fail
Returns:	OK response object
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.createNewEntry(
>>>     title='Some demo title',
>>>     category='ios'
>>> )
>>> print(s)

createNewSection(token: str, type: str, output: str, command: str, comment: str = 'saramPy') → dict¶

Create a new section. This will add to the existing entry.

Parameters:	token (str) – Valid token for the entry type (str) – Valid type. Ex. stdout output (str) – Output of a command/variable etc command (str) – Command executed to get the output comment – Comment to add, defaults to [‘saramPy’] comment – list, optional
Raises:	TypeError – Exception if type is not valid StatusNotOk – Exception on fail
Returns:	OK object
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.createNewSection(
>>>     token='080d33e0-demo-title',
>>>     type='stdout',
>>>     output='echo output',
>>>     command='echo',
>>>     comment='Demo comment'
>>> )
>>> print(s)

deleteChatMessage(token: str, chat_id: str) → dict¶

Delete a chat message from an entry

Parameters:	token (str) – A valid entry token chat_id (str) – A valid chat Id
Raises:	StatusNotOk – Exception on fail
Returns:	Response object
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.deleteChatMessage(
>>>     token='ef3ace10-test',
>>>     chat_id='5cc0e3baecfc8a16279b4756'
>>> )
>>> print(s)

deleteComment(token: str, dataid: str, commentId: str) → dict¶

Delete a comment from a section

Parameters:	token (str) – A valid entry token dataid (str) – A valid section data id commentId (str) – A valid comment id
Raises:	StatusNotOk – Exception on fail
Returns:	object with response
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.deleteComment(
>>>     token='ef3ace10-test',
>>>     dataid='f12489f0-6619-11e9-a6dd-df81fb7d1eca',
>>>     commentId='5cbfafd1038ef8ee06c18a3c'
>>> )
>>> print(s)

deleteEntry(token: str) → dict¶

Delete an entry entirely

Parameters:	token (str) – Valid token for entry
Raises:	StatusNotOk – Exception on fail
Returns:	OK object
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.deleteEntry('080d33e0-demo-title')
>>> print(s)

deleteSection(token: str, dataid: str) → dict¶

Delete a section. This will delete a single section in an entry

Parameters:	token (str) – Valid token for the entry dataid (str) – Valid dataid for the section to delete
Raises:	StatusNotOk – Exception on fail
Returns:	OK object
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.deleteSection(
>>>     token='080d33e0-demo-title',
>>>     dataid='12f45080-656e-11e9-be3a-05d3364ece32'
>>> )
>>> print(s)

entryAddDescription(token: str, description: str = None) → dict¶

Add or update the description text for an entry

Parameters:	token (str) – Valid token for entry description – Optional description for the entry, defaults to None description – str, optional
Raises:	StatusNotOk – Exception
Returns:	Response oject
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.entryAddDescription(
>>>     token='080d33e0-demo-title',
>>>     description='Some description',
>>> )
>>> print(s)

entryAddNotice(token: str, message: str, notice_type: str = 'info') → dict¶

Add or update a notice message for an entry

Parameters:	token (str) – Valid token for entry message (str) – The message for the notice notice_type – The severity level of the notice, defaults to info. Valid values are ‘success’, ‘info’, ‘warning’, ‘error’ notice_type – str, optional
Raises:	StatusNotOk – Exception
Returns:	Response oject
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.entryAddNotice(
>>>     token='080d33e0-demo-title',
>>>     notice_type='success',
>>>     message='Some notice message',
>>> )
>>> print(s)

entryAddPriority(token: str, priority: str = 'none') → dict¶

Add or update the priority of an entry.

Parameters:	token (str) – Valid token for entry priority – The priority/criticality/status of an enty, defaults to none. Valid values are ‘info’, ‘high’, ‘medium’, ‘low’, ‘critical’, ‘complete’, ‘none’ priority – str, optional
Raises:	StatusNotOk – Exception
Returns:	Response oject
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.entryAddPriority(
>>>     token='080d33e0-demo-title',
>>>     priority='high',
>>> )
>>> print(s)

entryChangeWorkspace(token: str, workspace: str) → dict¶

Change the workspace for an entry

Parameters:	token (str) – Valid token for entry workspace – Optional workspace for the entry workspace – str
Raises:	StatusNotOk – Exception
Returns:	Response oject
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.entryChangeWorkspace(
>>>     token='080d33e0-demo-title',
>>>     workspace='Some_workspace',
>>> )
>>> print(s)

entryDeleteDescription(token: str) → dict¶

Delete a description from an entry

Parameters:	token (str) – A valid Saram entry token
Raises:	StatusNotOk – Exception
Returns:	Response object
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.entryDeleteDescription(
>>>     token='080d33e0-demo-title'
>>> )
>>> print(s)

entryDeleteNotice(token: str) → dict¶

Delete a notice from an entry

Parameters:	token (str) – A valid Saram entry token
Raises:	StatusNotOk – Exception
Returns:	Response object
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.entryDeleteNotice(
>>>     token='080d33e0-demo-title'
>>> )
>>> print(s)

entryDeletePriority(token: str) → dict¶

Delete a priority from an entry

Parameters:	token (str) – A valid Saram entry token
Raises:	StatusNotOk – Exception
Returns:	Response object
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.entryDeletePriority(
>>>     token='080d33e0-demo-title'
>>> )
>>> print(s)

getAllChat(token: str) → dict¶

Get all chat messages associated with an entry

Parameters:	token (str) – A valid token
Raises:	StatusNotOk – Exception on fail
Returns:	Array of all chat objects
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.getAllChat(
>>>     token='ef3ace10-test'
>>> )
>>> print(s)

getAllEntries() → list¶

Gets an array of all the valid entries

Raises:	StatusNotOk – Exception on fail
Returns:	Array containing objects of all the entries
Return type:	list

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.getAllEntries()
>>> print(s)

getEnabledAuthModules(api_key: str) → dict¶

Get an array of all enabled auth modules for Saram

Raises:	StatusNotOk – Exception
Returns:	dict containing the valid API key and associated username
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.getEnabledAuthModules()
>>> print(s)

getEntry(token: str) → dict¶

Gets all the data associated with a single entry

Parameters:	token (str) – Valid token for entry
Raises:	StatusNotOk – Exception if not found
Returns:	object with all entry data
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.getEntry(token='080d33e0-demo-title')
>>> print(s)

getReport(token: str, render: bool = False) → str¶

Generate a markdown report for an entry. Can be optionally send to render the markdown

Parameters:	token (str) – A valid token render (bool, optional) – Render?, defaults to False
Raises:	StatusNotOk – Exception on fail
Returns:	Markdown scaffold
Return type:	str

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.getReport(
>>>     token='someDemotoken'
>>> )
>>> print(s)

getValidToken(title: str) → dict¶

Supply a title, and get a valid token back. This is useful when testing token creation, or when working with other API endpoints.

Parameters:	title (str) – Title to generate the token with
Raises:	StatusNotOk – Exception
Returns:	reponse dictionary object
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.getValidToken(
>>>     title='Some demo title'
>>> )
>>> print(s)

imageUploadImgbb(token: str, dataid: str) → dict¶

Delete a comment from a section

Parameters:	token (str) – A valid entry token dataid (str) – A valid section data id
Raises:	StatusNotOk – Exception on fail
Returns:	object with response
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.imageUploadImgbb(
>>>     token='ef3ace10-test',
>>>     dataid='f12489f0-6619-11e9-a6dd-df81fb7d1eca'
>>> )
>>> print(s)

markSection(token: str, dataid: str) → dict¶

Mark a section.

Parameters:	token (str) – Valid token for the entry dataid (str) – Valid section to add the comment to
Raises:	StatusNotOk – Exception on fail
Returns:	OK object
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.markSection(
>>>     token='080d33e0-demo-title',
>>>     dataid='bfe02810-656d-11e9-be3a-05d3364ece32',
>>> )
>>> print(s)

miscCreateAdmin(username: str, url: str) → list¶

Create an admin account on first Saram install

Raises:	StatusNotOk – Exception
Returns:	Array of log objects
Return type:	list

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.miscCreateAdmin(username='admin', url='http://localhost:8080/')
>>> print(s)

postChatMessage(token: str, message: str) → dict¶

Post a chat message to an entry

Parameters:	token (str) – A valid entry token message (str) – A valid message
Raises:	StatusNotOk – Exception on fail
Returns:	Response object
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.postChatMessage(
>>>     token='ef3ace10-test',
>>>     message='Message from Py'
>>> )
>>> print(s)

resetApiKey(old_apikey: str, username: str) → dict¶

Reset the API key

Parameters:	old_apikey (str) – Valid API key username (str) – Username associated with valid API key
Raises:	StatusNotOk – Exception on fail
Returns:	object containing new API key
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.resetApiKey(
>>>     old_apikey='oldSecretApiKey',
>>>     username='demoUser'
>>> )
>>> print(s)

resetPassword(password: str) → dict¶

Reset password

Parameters:	password (str) – A valid password
Raises:	StatusNotOk – Exception on fail
Returns:	object containing new API key
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.resetPassword(
>>>     password='newGoodPassword'
>>> )
>>> print(s)

updateChatMessage(token: str, chat_id: str, message: str) → dict¶

Update a chat message from an entry

Parameters:	token (str) – A valid entry token chat_id (str) – A valid chat Id message (str) – A valid message
Raises:	StatusNotOk – Exception on fail
Returns:	Response object
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.updateChatMessage(
>>>     token='ef3ace10-test',
>>>     chat_id='5cc0e3baecfc8a16279b4756'
>>>     message='Some message to update with'
>>> )
>>> print(s)

validateApiKey(api_key: str) → dict¶

Validate and API key and if valid, return the API and assciated username

Parameters:	api_key (str) – Valid API key
Raises:	StatusNotOk – Exception
Returns:	dict containing the valid API key and associated username
Return type:	dict

>>> from saramPy.api import SaramAPI
>>> saram = SaramAPI()
>>> s = saram.validateApiKey('secretApiKey')
>>> print(s)

Saram

Navigation

Related Topics