interpol

README

.. image:: logo.png
   :align: center

Interpol
========

**Interpol** is a minimal `string interpolation <https://en.wikipedia.org/wiki/String_interpolation>`_
library written in Go. It can be used to generate a series of strings from a set of rules.
This is useful for example for people doing penetration testing or fuzzing.


**Police** is a command-line interface for Interpol. It is not as powerful as embedding Interpol in your
own application (which allows you to create custom interpolators and modifiers) but still very handy if you are a
CLI type of person.

You can install Police from the `Snap store <https://snapcraft.io/police>`_ ::

    $ sudo snap install police

To build Police from source, install the Go compiler then execute this::

    $ go get -u bitbucket.org/vahidi/interpol/cmd/police/...


Usage example
-------------

Consider the following problem: you have forgotten your password to the company mainframe.
You do however remember that the password had the following format::

    <one of the Friends characters> <a digit> <a currency sign>

Since this is something that can be defined as a bunch of rules, we can use police to generate all possible combinations::

    # 'friends.txt' is a file containing one friends character per line
    $ police "{{file filename='friends.txt'}}{{counter min=0 max=9}}{{set data='£$¥€'}}"

    Rachel0£
    Monica0£
    Phoebe0£
    . . .
    Joey9€
    Chandler9€
    Gunther9€

You may now use these candidates with a password recovery tool to find your lost password in no time.


Interpolators
-------------

In our example above the rules were defined as expressions embedded in a string.
Evaluating expressions within strings is often called *string interpolation*,
hence we have chosen to call each rule fragment an "interpolation" and the logic behind it an "interpolator".


An interpolation has the following syntax::

    {{type parameter1=value1 parameter2=value2 ... }}

For example::

    {{counter min=1 max=10 step=3}}

The following interpolators are currently available::

    {{counter [min=0] [max=10] [step=1] [format="%d] }}
    {{random [min=0] [max=100] [count=5] [format="%d"] }}
    {{file filename="somefile" [count=-1] [mode=linear] }}
    {{set data="some input" [sep=""] [count=-1] [mode=linear] }}
    {{copy from="others-name" }}

Where

- [parameter=value] indicates an optional parameter, value is the default value
- valid values for mode are: linear, random or perm
- format is standard Go fmt.Printf() format string (which is fairly similar to C format strings)
- copy repeats the value of another interpolation (see below)


Copying
~~~~~~~

Interpolators may be given a name. This is needed when using copy::

    "{{counter name=mycounter}} {{copy from=mycounter}}"

This will yield "0 0", "1 1", and so on.


Modifiers
~~~~~~~~~

Interpolators can also have an output *modifier*.
Currently the following modifiers exist:

- *empty*: the empty string "" (ignores input)
- *len*: length of the input (in raw bytes, no fancy UTF-8 support)
- *bitflip*: randomly flip one bit (again, using raw bytes)
- *byteswap*: randomly swap two bytes (raw bytes again)
- *reverse*: reverse (for once, this one supports UTF-8)
- *trim*: trim text (remove space before and after)
- *base64*: base64 encode
- *toupper*: make all characters upper case
- *tolower*: make all characters lower case
- *capitalize*: capitalize each word
- *1337*: leet speak modifier (random upper/lower case)

For example, the following will yield "Yes", "No" and "Maybe"::

    {{set data="YES,no,mayBE" sep="," modifier=capitalize}}


API
---

Interpol can be used as a library in your own programs::

    package main

    import (
        "fmt"
        "log"
        "bitbucket.org/vahidi/interpol"
    )

    func main() {
        ip := interpol.New()
        vs, err := ip.AddMultiple(
            "{{counter min=10 max=33 step=7}}",
            "{{set data='ABCD' mode='linear'}}",
            "{{counter min=0 max=9}}",
        )

        if err != nil {
            log.Fatal(err)
        }

        for ip.Next() {
            fmt.Printf("%s-%s-%s\n", vs[0], vs[1], vs[2])
        }
    }
    // 10-A-0
    // 17-A-0
    // ...

Some more interesting examples can be found in the examples/ folder:

- **hackernews** - download 3 random HN comments from firebase
- **nena** - demonstrates use of copy
- **hodor** - as the name clearly implies this one teaches you to create custom interpolators
- **discordia** - demonstrates use of custom modifiers





License
-------

This library is licensed under the GNU GENERAL PUBLIC LICENSE, version 2 (GPLv2).

See the file LICENSE for more information.

Documentation

Index

• Variables
• func ReadFile(filename string) ([]string, error)
• type Handler
• type HandlerFactory
• type Interpol
  • func New() *Interpol
  • func (ip *Interpol) Add(text string) (*InterpolatedString, error)
  • func (ip *Interpol) AddHandler(typ string, creator HandlerFactory) error
  • func (ip *Interpol) AddModifier(typ string, modifier ModifierFactory) error
  • func (ip *Interpol) AddMultiple(texts ...string) ([]*InterpolatedString, error)
  • func (ip *Interpol) Next() bool
  • func (ip *Interpol) Reset()
• type InterpolatedString
  • func (ips *InterpolatedString) String() string
• type Modifier
• type ModifierFactory
• type Parameters
  • func (id *Parameters) GetInteger(name string, def int) int
  • func (id *Parameters) GetString(name string, def string) string

Variables

var Version = []int{0, 2, 0}

Version is library version number

Functions

func ReadFile

func ReadFile(filename string) ([]string, error)

ReadFile is a helper function to read non-empty lines from a file. The reason this is a public function is because it is also used by Police

Types

type Handler

type Handler interface {
	String() string

	// Get the next value, returns false if no more values are available
	Next() bool

	// Reset the handler and prepare the first value
	Reset()
}

Handler represents a handler for a certain type of interpolation

Note 1: Handler object should call Reset() when created Note 2: String() should be valid right after Reset() Note 3: Unlike Interpol, Next() after Reset() yields the _second_ value not first.

type HandlerFactory

type HandlerFactory func(ctx *Interpol, text string, data *Parameters) (Handler, error)

HandlerFactory creates a new handler for a given text or command

type Interpol

type Interpol struct {
	// contains filtered or unexported fields
}

Interpol context for an interpolation

func New

func New() *Interpol

New creates a new interpolator context

func (*Interpol) Add

func (ip *Interpol) Add(text string) (*InterpolatedString, error)

Add creates a new string to be interpolated

func (*Interpol) AddHandler

func (ip *Interpol) AddHandler(typ string, creator HandlerFactory) error

AddHandler adds a handler for a specific type of interpolator

func (*Interpol) AddModifier

func (ip *Interpol) AddModifier(typ string, modifier ModifierFactory) error

AddModifier registers a new modifier

func (*Interpol) AddMultiple

func (ip *Interpol) AddMultiple(texts ...string) ([]*InterpolatedString, error)

AddMultiple creates multiple strings to be interpolated

func (*Interpol) Next

func (ip *Interpol) Next() bool

Next calculates the next value

func (*Interpol) Reset

func (ip *Interpol) Reset()

Reset resets everything to its original state

type InterpolatedString

type InterpolatedString struct {
	// contains filtered or unexported fields
}

InterpolatedString contains an interpolator object

func (*InterpolatedString) String

func (ips *InterpolatedString) String() string

convert InterpolatedString to a string

type Modifier

type Modifier interface {
	Modify(string) string
}

Modifier interface represents any functions that modifies an interpolator

type ModifierFactory

type ModifierFactory func(ctx *Interpol, data *Parameters) (Modifier, error)

ModifierFactory creates a new modifier

type Parameters

type Parameters struct {
	Type       string
	Properties map[string]string
}

Parameters for an interpolator command in a more accesible form

func (*Parameters) GetInteger

func (id *Parameters) GetInteger(name string, def int) int

GetInteger returns an interpolation parameter as int

func (*Parameters) GetString

func (id *Parameters) GetString(name string, def string) string

GetString returns an interpolation parameter as string