Saram’s documentation

_images/logo.png

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)

Indices and tables