AdministrationGuide

VXE Administrator's Guide

Introduction

Start-up

One of VXE designe prioriyes ia an ease of use. Most of the tasks can be copleted through GUI. REST API is an integral part of VXE and can be used to manage multiple VXE enabled servers or for any other purposes.

There are two VXE userspace services: logger and gui. Logger loads VXE kernel module, starts GUI and collects violation logs prodiced by kernel module.

To start VXE manually, run following comman as root:

# service vxe-logger start

VXE services run as vxeuser.vxegroup.

To check VXE service status:

# service vxe-logger status
# service vxe-logger status

To stop VXE services:

# service vxe-logger stop

To check for VXE Kernel Module:

# lsmod
Module                  Size  Used by
vxe_lkm               171436  0
...

Look for vxe_lkm.

In production environment vxe-logger should be configure to start during the system start-up.

File locations

Services: /usr/lib/systemd/system/vxe-logger.service, /usr/lib/systemd/system/vxe-gui.service

Python service implementation: /usr/lib/python2.7/site-packages/vxe (may vary, based on particual Linux distribution)

VXED definitions: /var/vxe/conf

Violation logs: /var/vxe/log

Hashes of GUI user passwords: /var/vxe/config.json

Typical workflow

1. Select a program that should be protected (placed in Virtual Environment). This would protect the rest of the system from the selected program and its subprocesses. For testing purposes one can create a simple script and protect it.
2. Create VXED (in GUI), set the name and activation path of the VXED, which is path to the selected program. VXED is created with learning ("log violations") mode enabled.
3. Run the program.
4. Observe its status on GUI Dashboard.
5. After program is ended a violation log is available. It describes all resorces (system calls) used by the program during particular run.
6. Update VXED with the violation log (in GUI). Such an upadte will add resorces used by the program to VXED.
7. Adjust VXED. If the program accesses different files in the same directory during different runs, it may have sense to allow access to all files in prticular directory, etc.
8. Repeat steps 3-7, until no new violations are detected.
9. Swithch VXED production ("deny violations") mode. In this mode violations are logged and access to resources not included in VXED is denied.

VXEDs (VXE Descriptions) has a version number. It is increasing after each edit.

GUI

Log-in

After installation VXE accepts default credentials, username admin and passowrd 12345. Go to Config tab to change the password. Only one username is supported as of now.

Dashboard

Pic. 1

Dashoboards presents the current running status of VXE. Left pane lists enabled VXEDs. This VXEDs are installed into the Linux kernel. Idle section shows VXEDs that doesn't have any running VXEI (instances) associated with them. Running section represents VXEDs with currently active instances. Long 64-bit numbers are VXEI IDs. They differentiate VXEIs. Selecting any running VXED or VXEI displace corresponding processes on the right pane.

To log-out use VXE menu in the upper right corner. There is a red/green sign next to the VXE letters in this menu. Red means that there are running VXEIs with violations.

VXED Edit

This tab allows editing VXEDs.

Pic. 2

Left pane lists defined VXEDs. New is not an actual VXED, but used to create ne VXEDs. Marked checkobxes indicate enabled VXEDs. VXED can be enabled or disabled by changing the mark.

Right pane is VXED (VXE Description) itself.

The header part has following fields:

• Name - VXED name.
• Type - the only type currently supported is strict.
• Mode - log (log violtaions during learning phase) or deny (enforce restrictions in production phase).
• Preemtive - if checkbox is marked this VXED can be instantiated under another VXEI.
• Activation path - comma seprated list of executables that create VXEI.
• Version - VXED version.

Buttons:

• Save - save VXED.
• Update - update VXED by the contents of the applicable (having the same version numebr) violation logs.
• Cancel - cancel changes made to VXED a reload it from the server.
• Delete - delete VXED.

The section with system call rules is under the buttons. These rules describe which system calls with what parameters are allowed.

System call header includes system call index as used by Linux and name. Cliking on this header expands particular system call rules.

Each rule includes index, counter and system call arguments. If system call matches any rule - it is allowed.

Index defines sequence in which rules are matched.

Counter limits the number of matches. If this number is exhausted - rule is excluded from the matching process. If counter is "*" there is no limit on how many times the rule can be matched.

Arguments can be rpresented by file system paths and numbers. If argument in a rule is "*" it will match any corresponding value in the system call.

If argument is a number and not "*" it should match exactly.

Paths can have trailing "/+" or "/*". "/+" matches any filename, but doesn't include contents of the subdirectories. "/*" includes contnts of the subdirectories.

Double click on a row to edit a rule.

Index column can be used for the following actions:

• n (number) - move at this number if changed, old row moves down
• b - move to the begining of the table
• e - move to the end of the table
• - - delete this row
• + - add a row after the current

Above the rules there is Tools menu with following options:

• Allow all - allow this system call with any parameters without limiting number of calls
• Allow all with count - allow this system call with any parameters, but limit the number of calls by the sum of all calls in the table
• Delete all - remove this syscall from VXED completely

Logs

This tab shows existing violations logs.

Pic. 3

Live section of the left pane lists violation logs of the running VXEIs. If a log index is selected in the left pane, the log contenets is shown in the right pane.

Complete section of the left pane lists violation logs of the ended VXEIs. Logs are grouped by VXED names. Log indexes that can be applied to VXEDs (whose indixes match current index of particular VXED) are marked by bold font.

Buttons at the bottom left are applied to the logs with marked checkboxes. There are three such buttons:

• Apply - apply logs with marked checkboxes to VXED; only one VXED can be updated in a time
• Clear - remove marks from all marked checkboxes
• Delete - delete logs with marked checkboxes

Example

The following script will be used as an example:

1 2 3 4 5 6 7 8

#!/usr/bin/python from subprocess import call import time call(["ps", "-ef"]) time.sleep(30)

Path of the script is /home/slozovsky/vxe_test.py

You can create the similar script in your directiry for testing.

Create a new VXED

Go to VXED Edit tab. Select New. Fill in Name and Activation path. Use path of your script.

Pic. 4

Click Save button. Version number should become 1.

Enable VXED by marking the checkbox next to the VXED name test.

No system calls are defined (allowed) in the new VXED, so they all will be logged in the subsequent run.

Monitor execution

From the command line run your test script.

Monitor its execution through the Dashboard tab.

Pic. 5

Observe that status indicator in the upper right corner is red. That menas that there is VXEDI with violation logs. After script is finished check the logs.

Checking logs

At the Logs tab expand test logs. There is just one log is present 1. Select it. Contents of the log appears at the right pane.

Pic. 6

A number before system call name is conter. It indicates how many times this system call was executed with the given parameters.

There are two way to update VXED with the violations from the log. The first is from VXED Edit tab, by clicking Upadte button. GUI will automatically mark all applicable logs. The second way is to mark logs manually. This is what we do in current example.

Mark the checkbox before 1 log and click Apply button. This will bring us to the updated VXED.

Edit VXED

In the VXED Edit tab all changed system call definitions and rules are marked as changed. It makes easier to locate changes made by the update. In our example all rules are new, so all of them are marked as changed. VXED version is incremented.

Pic. 7

VXED should be generalized to become useful. Expand open syscall by clicking on it. We can see that there are many instances of accessing /proc/.... Let's allow our script read access to /proc/... with all subdirectories.

Double-click on any rule with /proc/... and change /proc/... to /proc/\*. Set counter fileld to \* and press Enter or click outside of the rule. GUI will integarate all /proc/... rules into one. Flag 0 menas read access.

Go through other system calls and do generalizations as you see fit.

Click Save button to save results.

Run the script multiple times

To get a complete VXED the script should be xecuted multiple times to reveal different exection paths and variances in using resources.

If there is no need to be very specific about some system calls - select Tools - Allow all. For example, we probably don't care about close system call and it's hard to create meningful rules for it.

Repeat previous steps multiple times until no violation logs are produced. At this point in time switch Mode to deny in VXED header above buttons.