tcell-agent 1.3.1

tCell.io Agent

pythonagent-tcell

A tCell.io security agent that instruments your python projects

Install

Installing via pip (will install latest tcell_agent)

~/projects> pip install tcell_agent

or to install a particular version:

~/projects> pip install tcell_agent==1.0.1

Install from source (assuming pythonagent-tcell source code is located at /tcellagent_src) run

~/projects> pip install /tcellagent_src

Install from compressed file. This assumes you downloaded project source in zip form from github to ~/Downloads/pythonagent-tcell-master.zip

~/projects> pip install ~/Downloads/pythonagent-tcell-master.zip

Running from application source directory

Switch to your project

~/projects> cd mydjango/

Obtain a tcell_agent.config file from TCell dashboard. Place it at the root of your project. For this example: ~/projects/mydjango/ Note: by default the agent looks for the tcell_agent.config in the current working directory as well as $(TCELL_AGENT_HOME)/tcell_agent.config

There are two ways you can load the tcell_agent: 1) use the tcell_agent binary to run your app and 2) load the tcell_agent via a wsgi.py file

1. Starting your project using the tcell_agent binary (logs, by default, will be available in tcell/logs/tcell_agent.log)

If you previously used

~/projects/mydjango> python manage.py runserver 0.0.0.0:8000

now use

~/projects/mydjango> tcell_agent run python manage.py runserver 0.0.0.0:8000

Alternatively, if you use a wsgy.py file to start your app:

assuming your (django) wsgi.py file looks something like this:

  import os
  from django.core.wsgi import get_wsgi_application
  from django_waitlist.settings import PROJECT_ROOT

  os.environ.setdefault("DJANGO_SETTINGS_MODULE", "django_waitlist.settings")
  application = get_wsgi_application()

modify your wsgi.py to load the tcell_agent like so

  import os
  from django.core.wsgi import get_wsgi_application
  from django_waitlist.settings import PROJECT_ROOT

  # optional: change default settings via ENV
  # os.environ['TCELL_AGENT_CONFIG'] = '/var/www/html/tcell/tcell_agent.config'
  # os.environ['TCELL_AGENT_HOME'] = '/var/www/html/tcell'
  import tcell_agent
  tcell_agent.init()

  os.environ.setdefault("DJANGO_SETTINGS_MODULE", "django_waitlist.settings")
  application = get_wsgi_application()

Running application from non source directory (e.g. creating a service to launch your app via linux utils)

let's say you have a service script (/etc/init.d/myapp.conf) that looks something like this

script
    set -a
    source /etc/environment
    exec /path/to/bin/uwsgi --ini uwsgi.ini
end script

load the tcell_agent by modifying it like so

script
    set -a
    source /etc/environment
    export TCELL_AGENT_CONFIG='/path/to/tcell-home/tcell_agent.config'
    export TCELL_AGENT_HOME='/path/to/tcell-home/tcell'
    exec /path/to/bin/tcell_agent /path/to/bin/uwsgi --ini uwsgi.ini
end script

If you don't want to modify your /etc/init.d/myapp.conf, modifying wsgi.py to load the agent should also work.

Common pitfalls

• If you're using tcell_agent binary, ensure it exists in your path.
• If you're using virtualenv make sure to load the environment before installing tcell_agent
• When specifying TCELL_AGENT_HOME ensure the app's user has correct read/write permissions to that directory.

Contributing

Install Dependencies

~/projects/pythonagent-tcell> pip install -r requirements.txt

Run Tests

~/projects/pythonagent-tcell> python setup.py test

or

~/projects/pythonagent-tcell> python -m nose