Contributing to OSRFramework

Reporting issues, bugs and fresh ideas

The way in which we track the issues regarding the software is by means of the issues page in Github's project site, which can be found here: https://github.com/i3visio/osrframework/issues. Whether you have experimented problems with the installation, you have found a bug in a new platform or you feel that we can add a new functionality, you can find the place to report them there. The only "rule" is to notify one error per issue to be able to track the problems independently, as well as trying to provide as much information as possible regarding the OS or version you are trying.

Extending OSRFramework

This section will provide information about how to extend the different tools found in the framework.

Creating new usufy.py wrappers as plugins

Since OSRFramework 0.13.0, we have added the possibility of creating new wrappers as plugins.

The basic things you should know in order to create a new wrapper are: * The structure of the URL that links to the profile. * The part of the HTML code that says that the user does NOT exist. * A valid nickname that has an active profile in the website.

For the example, we are going to use an invented socialnetwork: http://example.com/james is the URL of a user called james in that figured platform. The error returned is <title>404 not found</title>. Go to the plugins/wrappers folder in your home, copy and rename the wrapper.py.sample to example.py. Thus you will have a template that you will be able to modify.

First, we'll change the name of the wrapper and the tags:

class Example(Platform):
    """
        A <Platform> object for Example.
    """
    def __init__(self):
        """
            Constructor...
        """
        self.platformName = "Example"
        self.tags = ["test"]

We'll tell the framework, that this platform has usufy-style profile pages by setting to True the corresponding variable:

        ########################
        # Defining valid modes #
        ########################
        self.isValidMode = {}        
        self.isValidMode["phonefy"] = False
        self.isValidMode["usufy"] = True
        self.isValidMode["searchfy"] = False   

We will provide the URL patern:

        ######################################
        # Search URL for the different modes #
        ######################################
        # Strings with the URL for each and every mode
        self.url = {}        
        #self.url["phonefy"] = "http://anyurl.com//phone/" + "<phonefy>"
        self.url["usufy"] = "https://example.com/" + "<usufy>"       
        #self.url["searchfy"] = "http://anyurl.com/search/" + "<searchfy>"  

We will know tell if the platform needs credentials to work:

        ######################################
        # Whether the user needs credentials #
        ######################################
        self.needsCredentials = {}        
        #self.needsCredentials["phonefy"] = False
        self.needsCredentials["usufy"] = False
        #self.needsCredentials["searchfy"] = False

In some platforms, we may now that the usernames always match a given regular expression (for instance, Twitter does not allow '.' in a username). If this is the case, we can modify the validQuery attribute:

        #################
        # Valid queries #
        #################
        # Strings that will imply that the query number is not appearing
        self.validQuery = {}
        # The regular expression '.+' will match any non-empty query.
        #self.validQuery["phonefy"] = re.compile(".+")
        self.validQuery["usufy"] = re.compile(".+")   
        #self.validQuery["searchfy"] = re.compile(".+")

The last part, is telling the framework which is the message that appears when the user is not present. This is an array, so more than one message can be used here.

        ###################
        # Not_found clues #
        ###################
        # Strings that will imply that the query number is not appearing
        self.notFoundText = {}
        #self.notFoundText["phonefy"] = []
        self.notFoundText["usufy"] = ["<title>404 not found</title>"]
        #self.notFoundText["searchfy"] = []  

And that's almost all. You can now test OSRFramework as usual. A new option will be available the next time you run the application.

Contributing code

If you want us to include your own wrapper, you will be able to extend the whole framework. Think about the wrapper Whether you want to add a new wrapper or fix a bug, the basic instructions to contribute and perform a pull request on Github are the following (we assume that you have installed Git by yourself, so please follow the instructions in the project's website to install it on your system https://git-scm.com/downloads). We will assume that the username for this test is osrframework_contributor.

First of all, logged in Github and fork the repository by pressing the corresponding button in https://github.com/i3visio/osrframework. This will create a copy of the repository under your profile (i. e.: https://github.com/osrframework_contributor/osrframework).

You can clone your forked repository now:

# This is an example! Change "osrframework_contributor" for your nick!
git clone https://github.com/osrframework_contributor/osrframework
cd osrframework

Then, you can modify any file you want, for example, adding the new wrapper that you have created in the previous case.

# Copying the file to the wrappers folder
mv ~/.config/OSRFramework/plugins/wrappers/example.py ./osrframework/wrappers/

Whenever you want, you can add the changes performed to the Git index to keep track of what you have changed and prepar it for the commit.

# Add one file
git add ./osrframework/wrappers/example.py
# Or adding all the files modified... Just be a little bit more careful
# git add -A

Once you are happy with the changes (and you have tested them!), you can commit the changes with a descriptive message.

git commit -m "Adding a new wrapper as example.py."

You have to push the changes to your Github project.

git push origin

You're almost there. You can now go to your project's website (http://github.com/osrframework_contributor/osrframework) and click in the Pulls tab or going directly to it by appending pulls to your forked URL, something similar to https://github.com/osrframework_contributor/osrframework/pulls. Then provide there as much detail as you can about the contents of the pull request and shortly we will evaluate the changes and pushed it upstream.

NOTE: a similar procedure can be performed to add new patterns to entify.py.

Style guide

Just a few things to be taken into account: * Use four spaces ' ' instead of a tab for identing blocks. * Provide useful and not trivial comments in English to the code you write. * Classes should start with a capitalised initial letter. * As a convention, wrappers inside the platform_selection.py should be in alphabetical order. Anyone wants to find things easily!

Licensing

The only thing we expect from other authors'code is to use a GPL-compatible license for their code, preferably GPLv3+ itself. We hope that anybody can use this tool for free (as in Free Software Foundation's four freedoms, not as in free beer), so help us to do it.