Welcome to forumsentry-sdk-for-python¶

Quickstart¶

Installation¶

You can install the latest version of forumsentry with:

pip install forumsentry

Basic Usage¶

Import the Forum Sentry API and start using methods:

from forumsentry.api import api

forumsentry = api(username="admin",password="password")

# get a list of all listenerPolices
forumsentry.get_listener_polices()

Tutorial¶

Coming soon.

API Reference¶

If you are looking for information on a specific function, class or method, this part of the documentation is for you.

API¶

Note

Unless otherwise noted all arguments are of the str type.

forumsentry¶

forumsentry.api¶

forumsentry.config¶

forumsentry.errors¶

forumsentry.configuration_import_api¶

forumsentry.http_listener_policy_api¶

forumsentry.http_remote_policy_api¶

forumsentry.json_policies_api¶

forumsentry.serialization¶

forumsentry.task_list_groups_api¶

forumsentry.task_lists_api¶

forumsentry.documents_api¶

Models Reference¶

List of models which are currently supported

Models¶

Note

Unless otherwise noted all arguments are of the str type.

forumsentry_api¶

Models which represent objects in the forum sentry.

forumsentry_api.models¶

forumsentry_api.models.http_listener_policy¶

forumsentry_api.models.http_listener_policy¶: alias of forumsentry_api.models.http_listener_policy

forumsentry_api.models.http_remote_policy¶

forumsentry_api.models.http_remote_policy¶: alias of forumsentry_api.models.http_remote_policy

forumsentry_api.models.json_policies¶

forumsentry_api.models.json_policies¶: alias of forumsentry_api.models.json_policies

forumsentry_api.models.task_list_group¶

forumsentry_api.models.task_list_group¶: alias of forumsentry_api.models.task_list_group

forumsentry_api.models.task_list¶

forumsentry_api.models.task_list¶: alias of forumsentry_api.models.task_list

forumsentry_api.models.virtual_directory¶

forumsentry_api.models.virtual_directory¶: alias of forumsentry_api.models.virtual_directory

forumsentry_api.models.document¶

forumsentry_api.models.document¶: alias of forumsentry_api.models.document

Developer Documentation¶

Installing Development Environment¶

Your life will be a lot better if you use a virtualenv when working with python.

Fork and Clone this repo
Install python-pip and virtualenv if you do not already have it.
Create a new virtualenv with virtualenv forumsentry-sdk-for-python.
Actiavte the new virtualenv with source forumsentry-sdk-for-python/bin/activate.
Run make dev
Hack away!

Running Tests¶

Tests can be found in the tests directory.

You can run tests with make tests.

If you want to run a specific test file you can do so with:

python -m unittest tests/sentry/test_$MODULE.py

This project has two main types of tests.

Unit tests. These are tests of specific functions using mocked API data.
Integration tests. These are tests that actually hit a forum sentry device. Unfortunately, this will need to be setup by the developer and conectivity from the machine running the tests established.

In order to run the intergration tests then setup the following environment variables.

::: export FORUM_REST_API_HOST=forumsentry-dev export FORUM_REST_API_PORT=8081 export FORUM_REST_API_USER=admin export FORUM_REST_API_PASSWORD=*******

Code Coverage¶

This project attempts to have 100% code coverage. when you run make test code coverage is automatically ran. You can view the code coverage report locally by opening up the index.html file in the htmlcov directory that gets created when you run make test.

Swagger¶

The forumsentry provide swagger documentation. A tools directory is provided with a script to generate python models from the swagger api.

To run this

cd tools
export FORUM_REST_API_HOST=xxxxxxxxxxxxx
export FORUM_REST_API_USER=xxxxxxxxxxxxx
export FORUM_REST_API_PASSWORD=xxxxxxxxxxx
./generate_code.sh

This will place the models swagger generated code in a folder _build

Note: _build is listed in the .gitignore file. For now you will need to manually merge/extract anything useful from there. *

If you need to make changes to the generate code first see if it can be made in the templates under tools/templates/python. That way adding new models will be easier in the future.

Documentation¶

This project uses sphinx for documentation. You can generate the latest docs locally by running make docs. You can then view them by opening up the index.html file in the docs/build/html directory.

Linting and Style¶

This project follows the PEP 8 style guidelines. You can install pylint in order to ensure that all of your code is compliant with this standard.

Generating p12 for testing¶

When working with the KeyPairs API we need a p12 to upload. To create one use the following

#Create a temp server cert with SANs
export CNAME=forumsentry-sdk-for-python
export PASSWORD=password
#create private key
openssl genrsa -out ${CNAME}.key 4096
#create temp CA
openssl req -new -x509 -sha256 -nodes -days 3650  -key ${CNAME}.key -out ${CNAME}-ca.pem -subj "/CN=${CNAME}-ca"
#cp ${CNAME}-ca.pem /etc/pki/ca-trust/source/anchors/${CNAME}-ca.pem; update-ca-trust extract
#create config file for request/signing
cat /etc/pki/tls/openssl.cnf > ${CNAME}.cnf
cat >> ${CNAME}.cnf  << END
[req]
req_extensions = v3_req

[ v3_req ]

# Extensions to add to a certificate request

basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = ${CNAME}
END

#Generate CSR
openssl req -subj "/CN=${CNAME}" -sha256 -new -key ${CNAME}.key -out ${CNAME}.csr  -config ${CNAME}.cnf
#Sign the CSR with the temp CA
openssl x509 -req  -sha256 -in ${CNAME}.csr -CA ${CNAME}-ca.pem -CAkey ${CNAME}.key -CAcreateserial -out ${CNAME}.cer -days 730 -extfile ${CNAME}.cnf -extensions v3_req
#Create passphrase file
echo -n ${PASSWORD} > .${CNAME}_passphrase

#Create p12
openssl pkcs12 -export -out  ${CNAME}.p12  -in ${CNAME}.cer -inkey ${CNAME}.key -certfile ${CNAME}-ca.pem -password file:.${CNAME}_passphrase
#Create jks
keytool -importkeystore -srckeystore ${CNAME}.p12 -srcstoretype pkcs12 -destkeystore ${CNAME}.jks -deststoretype JKS -srcstorepass ${PASSWORD}  -deststorepass ${PASSWORD}

Developer Documentation¶

Logging¶

Defaults¶

By default, (if you do nothing) the forumsentry sdk for python will setup the root logger to stream to stderr.

This works better with ansible and other tools that may call it.

Additionally logging level is set to FATAL which means no messages will be emitted from forumsentry sdk for python.

Debugging¶

If the environment FSENTRY_DEBUG is set then the logging level will be set to debug

export FSENTRY_DEBUG=TRUE

Config¶

A yaml config file can be used to gain full control over logging.

Set the environment variable FSENTRY_LOG_YAML to the location of your yaml config file.

E.g

export FSENTRY_LOG_YAML=/etc/fsentry.yaml

The default location if the FSENTRY_LOG_YAML is ~/fsentry_log.yaml

If the file given by FSENTRY_LOG_YAML or the default ~/fsentry_log.yaml exists then those settings will be used.

If the file is not found then the default above will be used.

See below for an example config

---

#https://docs.python.org/2/library/logging.config.html#logging-config-dictschema

version: 1
disable_existing_loggers: False
formatters:
    simple:
        format: "%(asctime)s - %(levelname)s - %(name)s - %(module)s.%(funcName)s: %(message)s"

handlers:
    console:
        class: logging.StreamHandler
        level: ERROR
        formatter: simple
        stream: ext://sys.stderr


    debug_file_handler:
        class: logging.handlers.RotatingFileHandler
        level: DEBUG
        formatter: simple
        filename: /tmp/logs/debug.log
        maxBytes: 10485760 # 10MB
        backupCount: 20
        encoding: utf8

    info_file_handler:
        class: logging.handlers.RotatingFileHandler
        level: INFO
        formatter: simple
        filename: /tmp/logs/info.log
        maxBytes: 10485760 # 10MB
        backupCount: 20
        encoding: utf8

    error_file_handler:
        class: logging.handlers.RotatingFileHandler
        level: ERROR
        formatter: simple
        filename: /tmp/logs/errors.log
        maxBytes: 10485760 # 10MB
        backupCount: 20
        encoding: utf8

loggers:
    forumsentry:
        level: DEBUG
        handlers: [console, debug_file_handler, info_file_handler, error_file_handler]
        propagate: false
    urllib3:
        level: CRITICAL
        handlers: [console, info_file_handler, error_file_handler]
root:
    level: CRITICAL
    handlers: [console, info_file_handler, error_file_handler]

Changelog¶

Here you can see the full list of changes between each forumsentry-sdk-for-python release.

Version 0.1¶

Released on Novemeber 17, 2017

Basic project setup.
- Continuous Integration with CircleCI
- Packaging and uploading to PyPI
- Code Coverage
- Testing with unittest
Basic Documentation in place

Attribution¶

This project relies on the wonderful requests library for all HTTP requests. This library is licensed under the Apache License, Version 2.0.