Github url

maybe

by p-e-w

p-e-w /maybe

:open_file_folder: :rabbit2: :tophat: See what a program does before deciding whether you really wa...

6.4K Stars 178 Forks Last release: over 4 years ago (v0.4.0) 78 Commits 5 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

| Package | | | Tests | |


rm -rf pic\*

Are you sure? Are you one hundred percent sure?

maybe

...

... allows you to run a command and see what it does to your files without actually doing it! After reviewing the operations listed, you can then decide whether you really want these things to happen or not.

Screenshot

What is this sorcery?!?

maybe

runs processes under the control of ptrace (with the help of the excellent python-ptrace library). When it intercepts a system call that is about to make changes to the file system, it logs that call, and then modifies CPU registers to both redirect the call to an invalid syscall ID (effectively turning it into a no-op) and set the return value of that no-op call to one indicating success of the original call.

As a result, the process believes that everything it is trying to do is actually happening, when in reality nothing is.

That being said,

maybe

should :warning: NEVER :warning: be used to run untrusted code on a system you care about! A process running under

maybe

can still do serious damage to your system because only a handful of syscalls are blocked. It can also check whether an operation such as deleting a file succeeded using read-only syscalls, and alter its behavior accordingly. Therefore, a rerun without restrictions is not guaranteed to always produce the displayed operations.

Currently,

maybe

is best thought of as an (alpha-quality) "what exactly will this command I typed myself do?" tool.

Installation

maybe

runs on Linux :penguin: and requires Python 2.7+/3.3+ :snake:. If you have the pip package manager, all you need to do is run

pip install maybe

either as a superuser or from a virtualenv environment. To develop

maybe

, clone the repository and run

pip install -e .

in its main directory to install the package in editable mode.

Usage

maybe [options] command [argument ...]

Positional arguments

| Argument | Description | | --- | --- | |

command

| the command to run under

maybe

's control | |

argument ...

| argument(s) to pass to

command

|

Optional arguments

| Argument | Description | | --- | --- | |

-a OPERATION ...

,

--allow OPERATION ...

                                              | allow the command to perform the specified operation(s). all other operations will be denied. possible values for

OPERATION

are:

change\_owner

,

change\_permissions

,

create\_directory

,

create\_link

,

create\_write\_file

,

delete

,

move

; as well as any filter scopes defined by loaded plugins | |

-d OPERATION ...

,

--deny OPERATION ...

| deny the command the specified operation(s). all other operations will be allowed. see

--allow

for a list of possible values for

OPERATION

.

--allow

and

--deny

cannot be combined | |

-p FILE ...

,

--plugin FILE ...

| load the specified plugin script(s) | |

-l

,

--list-only

| list operations without header, indentation and rerun prompt | |

--style-output {yes,no,auto}

| colorize output using ANSI escape sequences (

yes

/

no

) or automatically decide based on whether stdout is a terminal (

auto

, default) | |

-v

,

--verbose

| if specified once, print every filtered syscall. if specified twice, print every syscall, highlighting filtered syscalls | |

--version

| show program's version number and exit | |

-h

,

--help

| show a help message and exit |

Plugin API

By default,

maybe

intercepts and blocks all syscalls that can make permanent modifications to the system. For more specialized syscall filtering needs,

maybe

provides a simple yet powerful plugin API. Filter plugins are written in pure Python and use the same interfaces as [

maybe

's built-in filters](https://github.com/p-e-w/maybe/blob/master/maybe/filters).

The public API is composed of the following two members:

maybe.

T

A Blessings

Terminal

object that can be used to format console output (such as

operation

as documented below). Output formatted with this object automatically complies with the

--style-output

command line argument.

maybe.

register\_filter(syscall, filter\_function, filter\_scope=None)

Add the filter

filter\_function

to the filter registry. If the filter is enabled (which is the default, but can be altered with the

--allow

and

--deny

command line arguments), it intercepts all calls to

syscall

made by the controlled process.

filter\_scope

determines the key to be used in conjunction with

--allow

and

--deny

to enable/disable the filter (multiple filters can share the same key). If

filter\_scope

is omitted or

None

, the last part of the plugin's module name is used.

filter\_function

itself must conform to the signature

filter\_function(process, args)

.

process

is a [

Process

](https://github.com/p-e-w/maybe/blob/master/maybe/process.py) control object that can be used to inspect and manipulate the process, while

args

is the list of arguments passed to the syscall in the order in which they appear in the syscall's signature. If an argument represents a (pointer to a) filename, the argument will be of type

str

and contain the filename, otherwise it will be of type

int

and contain the numerical value of the argument.

When called,

filter\_function

must return a tuple

(operation, return\_value)

.

operation

can either be a string description of the operation that was prevented by the filter, to be printed after the process terminates, or

None

, in which case nothing will be printed.

return\_value

can either be a numerical value, in which case the syscall invocation will be prevented and the return value received by the caller will be set to that value, or

None

, in which case the invocation will be allowed to proceed as normal.

Example

Here,

maybe

's plugin API is used to implement an exotic type of access control: Restricting read access based on the content of the file in question. If a file being opened for reading contains the word SECRET, the plugin blocks the

open

/

openat

syscall and returns an error.

read\_secret\_file.py
from os import O\_WRONLY from os.path import isfile from maybe import T, register\_filter def filter\_open(path, flags): if path.startswith("/home/") and isfile(path) and not (flags & O\_WRONLY): with open(path, "r") as f: if "SECRET" in f.read(): return "%s %s" % (T.red("read secret file"), T.underline(path)), -1 else: return None, None else: return None, None register\_filter("open", lambda process, args: filter\_open(process.full\_path(args[0]), args[1])) register\_filter("openat", lambda process, args: filter\_open(process.full\_path(args[1], args[0]), args[2]))

Indeed, the plugin works as expected:

[[email protected]]$ maybe --plugin read\_secret\_file.py --deny read\_secret\_file -- bash $ echo "This is a normal file." \> file\_1 $ echo "This is a SECRET file." \> file\_2 $ cat file\_1 This is a normal file. $ cat file\_2 cat: file\_2: Operation not permitted

License

Copyright © 2016-2017 Philipp Emanuel Weidmann ([email protected])

Released under the terms of the GNU General Public License, version 3

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.