nitro package

Submodules

nitro.event module

class nitro.event.NitroEvent(nitro_event_str, vcpu_io)

Bases: object

NitroEvent represents a low-level system event. It contains information about the state of the machine when the system was stopped.

as_dict()

Return dict representation of the event

direction

Event direction. Are we entering or exiting a system call

get_register(register)

Get register value from the event

regs

Register state

sregs

Special register state

time
type

System call mechanism used

update_register(register, value)

Change individual register’s values

vcpu_io

Handle to the VCPU where the event originated

vcpu_nb

VCPU number

class nitro.event.SyscallDirection

Bases: enum.Enum

System call direction

enter = 0
exit = 1
class nitro.event.SyscallType

Bases: enum.Enum

System call mechanism

syscall = 1
sysenter = 0

nitro.kvm module

Low-level interface to KVM facilities. This module enables the use of Nitro’s enhanced KVM capabilities.

class nitro.kvm.DTable

Bases: _ctypes.Structure

base

Structure/Union member

limit

Structure/Union member

padding

Structure/Union member

class nitro.kvm.IOCTL

Bases: object

Class for making IOCTL calls

LIBC_6 = 'libc.so.6'
close()
fd
libc
make_ioctl(request, arg)
class nitro.kvm.KVM

Bases: nitro.kvm.IOCTL

Class for connecting to the KVM and attaching to virtual machines.

KVM_NITRO_ATTACH_VM = <MagicMock name='mock.IOW()' id='47824065995104'>
KVM_NODE = '/dev/kvm'
attach_vm(pid)

Attach to KVM virtual machine

Parameters:pid (int) – pid of the Qemu process to attach to.
Raises:RuntimeError
kvm_file
class nitro.kvm.NitroEventStr

Bases: _ctypes.Structure

direction

Structure/Union member

present

Structure/Union member

regs

Structure/Union member

sregs

Structure/Union member

type

Structure/Union member

class nitro.kvm.NitroVCPUs

Bases: _ctypes.Structure

fds

Structure/Union member

ids

Structure/Union member

num_vcpus

Structure/Union member

class nitro.kvm.Regs

Bases: _ctypes.Structure

r10

Structure/Union member

r11

Structure/Union member

r12

Structure/Union member

r13

Structure/Union member

r14

Structure/Union member

r15

Structure/Union member

r8

Structure/Union member

r9

Structure/Union member

rax

Structure/Union member

rbp

Structure/Union member

rbx

Structure/Union member

rcx

Structure/Union member

rdi

Structure/Union member

rdx

Structure/Union member

rflags

Structure/Union member

rip

Structure/Union member

rsi

Structure/Union member

rsp

Structure/Union member

class nitro.kvm.SRegs

Bases: _ctypes.Structure

apic_base

Structure/Union member

cr0

Structure/Union member

cr2

Structure/Union member

cr3

Structure/Union member

cr4

Structure/Union member

cr8

Structure/Union member

cs

Structure/Union member

ds

Structure/Union member

efer

Structure/Union member

es

Structure/Union member

fs

Structure/Union member

gdt

Structure/Union member

gs

Structure/Union member

idt

Structure/Union member

interrupt_bitmap

Structure/Union member

ldt

Structure/Union member

ss

Structure/Union member

tr

Structure/Union member

class nitro.kvm.Segment

Bases: _ctypes.Structure

avl

Structure/Union member

base

Structure/Union member

db

Structure/Union member

dpl

Structure/Union member

g

Structure/Union member

l

Structure/Union member

limit

Structure/Union member

padding

Structure/Union member

present

Structure/Union member

s

Structure/Union member

selector

Structure/Union member

type

Structure/Union member

unusable

Structure/Union member

class nitro.kvm.VCPU(vcpu_nb, vcpu_fd)

Bases: nitro.kvm.IOCTL

Class that allows controlling and inspecting the state of an individual virtual CPU.

KVM_NITRO_CONTINUE = <MagicMock name='mock.IO()' id='47824066019680'>

Request to continue

KVM_NITRO_GET_EVENT = <MagicMock name='mock.IOR()' id='47824066015584'>

Request for retrieving event

KVM_NITRO_GET_REGS = <MagicMock name='mock.IOR()' id='47824066015584'>

Request to get register state

KVM_NITRO_GET_SREGS = <MagicMock name='mock.IOR()' id='47824066015584'>

Request to get special registers

KVM_NITRO_SET_REGS = <MagicMock name='mock.IOW()' id='47824065995104'>

Request to set register state

KVM_NITRO_SET_SREGS = <MagicMock name='mock.IOW()' id='47824065995104'>

Request to set special registers

continue_vm()

Continue virtual machine execution

get_event()

Retrieve event from the virtual machine

Return type:NitroEventStr
get_regs()

Get registers from the virtual machine.

Return type:Regs
get_sregs()

Get special registers from the virtual machine.

Return type:SRegs
set_regs(regs)

Set registers for the virtual machine.

Parameters:regs (Regs) – Values for registers
set_sregs(sregs)

Set special registers for the virtual machine.

Parameters:sregs (SRegs) – Values for special registers
vcpu_nb
class nitro.kvm.VM(vm_fd)

Bases: nitro.kvm.IOCTL

Class that allows low-level control of KVM virtual machines.

VM makes it possible to attach to machine’s virtual CPUs and add system call filters.

KVM_NITRO_ADD_SYSCALL_FILTER = <MagicMock name='mock.IOR()' id='47824066015584'>

Request for adding system call filter

KVM_NITRO_ATTACH_VCPUS = <MagicMock name='mock.IOR()' id='47824066015584'>

Reguest for attaching to a virtual CPU

KVM_NITRO_REMOVE_SYSCALL_FILTER = <MagicMock name='mock.IOR()' id='47824066015584'>

Request for removing system call filter

KVM_NITRO_SET_SYSCALL_TRAP = <MagicMock name='mock.IOW()' id='47824065995104'>

Request for setting system call trap

add_syscall_filter(syscall_nb)
attach_vcpus()

Attach to virtual CPUs

Return type:List of VCPUs
remove_syscall_filter(syscall_nb)
set_syscall_trap(enabled)
vcpus_struct

nitro.libvmi module

class nitro.libvmi.Libvmi(vm_name)

Bases: object

destroy()
failures
get_offset(offset_name)
get_ostype()
libvmi
opaque_vmi
pidcache_flush()
read_32(vaddr, pid)
read_addr_ksym(symbol)
read_addr_va(vaddr, pid)
read_str_va(vaddr, pid)
read_va(vaddr, pid, count)
rvacache_flush()
stats
symcache_flush()
translate_ksym2v(symbol)
translate_kv2p(vaddr)
translate_v2ksym(vaddr)
v2pcache_flush(dtb=0)
vmi
write_va(vaddr, pid, buffer)
exception nitro.libvmi.LibvmiError

Bases: Exception

class nitro.libvmi.VMIOS

Bases: enum.Enum

LINUX = 1
UNKNOWN = 0
WINDOWS = 2

nitro.listener module

class nitro.listener.Listener(domain)

Bases: object

Class for listening to events from a virtual machine.

add_syscall_filter(syscall_nb)

Add system call filter to a virtual machine

current_cont_event
domain

Libvirt domain that the Listener is monitoring

futures
kvm_io
listen()

Generator yielding NitroEvents from the virtual machine

listen_vcpu(vcpu_io, queue)

Listen to an individual virtual CPU

pid

Pid of the QEMU instance that is being monitored

queue
remove_syscall_filter(syscall_nb)

Remove system call filter form a virtual machine

set_traps(enabled)
stop()

Stop listening for system calls

stop_listen()

Stop listening for events

stop_request
vcpus_io
vm_io
exception nitro.listener.QEMUNotFoundError

Bases: Exception

nitro.listener.find_qemu_pid(vm_name)

Find QEMU’s PID that is associated with a given virtual machine

Parameters:vm_name (str) – libvirt domain name
Return type:int

nitro.nitro module

class nitro.nitro.Nitro(domain, introspection=True, syscall_filtering=True)

Bases: object

listen()
stop()

nitro.syscall module

class nitro.syscall.Syscall(event, full_name, name, process, args)

Bases: object

Class representing system call events.

In contrast to NitroEvent events, Syscall class offers a higher-level view of what is happening inside the virtual machine. The class enables access to information about the process that created the event and makes it possible to access call’s arguments.

args

Arguments passed to the call

as_dict()

Retrieve a dict representation of the system call event.

event

Associated low-level NitroEvent

full_name

Full name of the systme call handler (eg. SyS_write)

hook

Hook associated with the event

name

Short “cleaned up” name of the system call handler (eg. write)

process

Process that produced the event

Module contents