scap.h

Go to the documentation of this file.

/*
Copyright (C) 2013-2018 Draios Inc dba Sysdig.
 
This file is part of sysdig.
 
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
 
    http://www.apache.org/licenses/LICENSE-2.0
 
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
 
*/
 
#pragma once
 
#ifdef __cplusplus
extern "C" {
#endif
 
// Public structs and defines
 
//
// Forward declarations
//
typedef struct scap scap_t;
typedef struct ppm_evt_hdr scap_evt;
 
struct iovec;
 
//
// Core types
//
#ifndef __APPLE__
#include <time.h>
#endif
#include "uthash.h"
#include "./common/sysdig_types.h"
#include "./driver/ppm_events_public.h"
 
//
// Return types
//
#define SCAP_SUCCESS 0
#define SCAP_FAILURE 1
#define SCAP_TIMEOUT -1
#define SCAP_ILLEGAL_INPUT 3
#define SCAP_NOTFOUND 4
#define SCAP_INPUT_TOO_SMALL 5
#define SCAP_EOF 6
#define SCAP_UNEXPECTED_BLOCK 7
#define SCAP_VERSION_MISMATCH 8
#define SCAP_NOT_SUPPORTED 9
 
//
// Last error string size for scap_open_live()
//
#define SCAP_LASTERR_SIZE 256
 
typedef struct scap_stats
{
    uint64_t n_evts; 
    uint64_t n_drops; 
    uint64_t n_drops_buffer; 
    uint64_t n_drops_pf; 
    uint64_t n_drops_bug; 
    uint64_t n_preemptions; 
    uint64_t n_suppressed; 
    uint64_t n_tids_suppressed; 
}scap_stats;
 
typedef struct evt_param_info
{
    const char* name; 
    uint32_t type; 
    uint32_t len; 
    char* val; 
}evt_param_info;
 
#define SCAP_MAX_PATH_SIZE 1024
#define SCAP_MAX_ARGS_SIZE 4096
#define SCAP_MAX_ENV_SIZE 4096
#define SCAP_MAX_CGROUPS_SIZE 4096
#define SCAP_MAX_SUPPRESSED_COMMS 32
 
typedef enum scap_fd_type
{
    SCAP_FD_UNINITIALIZED = -1,
    SCAP_FD_UNKNOWN = 0,
    SCAP_FD_FILE = 1,
    SCAP_FD_DIRECTORY = 2,
    SCAP_FD_IPV4_SOCK = 3,
    SCAP_FD_IPV6_SOCK = 4,
    SCAP_FD_IPV4_SERVSOCK = 5,
    SCAP_FD_IPV6_SERVSOCK = 6,
    SCAP_FD_FIFO = 7,
    SCAP_FD_UNIX_SOCK = 8,
    SCAP_FD_EVENT = 9,
    SCAP_FD_UNSUPPORTED = 10,
    SCAP_FD_SIGNALFD = 11,
    SCAP_FD_EVENTPOLL = 12,
    SCAP_FD_INOTIFY = 13,
    SCAP_FD_TIMERFD = 14,
    SCAP_FD_NETLINK = 15,
    SCAP_FD_FILE_V2 = 16
}scap_fd_type;
 
typedef enum scap_l4_proto
{
    SCAP_L4_UNKNOWN = 0, 
    SCAP_L4_NA = 1, 
    SCAP_L4_TCP = 2,
    SCAP_L4_UDP = 3,
    SCAP_L4_ICMP = 4,
    SCAP_L4_RAW = 5, 
}scap_l4_proto;
 
typedef struct scap_fdinfo
{
    int64_t fd; 
    uint64_t ino; 
    scap_fd_type type; 
    union
    {
        struct
        {
          uint32_t sip; 
          uint32_t dip; 
          uint16_t sport; 
          uint16_t dport; 
          uint8_t l4proto; 
        } ipv4info; 
        struct
        {
            uint32_t sip[4]; 
            uint32_t dip[4]; 
            uint16_t sport; 
            uint16_t dport; 
            uint8_t l4proto; 
        } ipv6info; 
        struct
        {
          uint32_t ip; 
          uint16_t port; 
          uint8_t l4proto; 
        } ipv4serverinfo; 
        struct
        {
            uint32_t ip[4]; 
            uint16_t port; 
            uint8_t l4proto; 
        } ipv6serverinfo; 
        struct
        {
            uint64_t source; 
            uint64_t destination; 
            char fname[SCAP_MAX_PATH_SIZE]; 
        } unix_socket_info; 
        struct
        {
            uint32_t open_flags; 
            char fname[SCAP_MAX_PATH_SIZE]; 
            uint32_t mount_id; 
            uint32_t dev; 
        } regularinfo; 
        char fname[SCAP_MAX_PATH_SIZE];  
    }info;
    UT_hash_handle hh; 
}scap_fdinfo;
 
typedef struct scap_threadinfo
{
    uint64_t tid; 
    uint64_t pid; 
    uint64_t ptid; 
    uint64_t sid; 
    uint64_t vpgid; 
    char comm[SCAP_MAX_PATH_SIZE+1]; 
    char exe[SCAP_MAX_PATH_SIZE+1]; 
    char exepath[SCAP_MAX_PATH_SIZE+1]; 
    char args[SCAP_MAX_ARGS_SIZE+1]; 
    uint16_t args_len; 
    char env[SCAP_MAX_ENV_SIZE+1]; 
    uint16_t env_len; 
    char cwd[SCAP_MAX_PATH_SIZE+1]; 
    int64_t fdlimit; 
    uint32_t flags; 
    uint32_t uid; 
    uint32_t gid; 
    uint32_t vmsize_kb; 
    uint32_t vmrss_kb; 
    uint32_t vmswap_kb; 
    uint64_t pfmajor; 
    uint64_t pfminor; 
    int64_t vtid;
    int64_t vpid;
    char cgroups[SCAP_MAX_CGROUPS_SIZE];
    uint16_t cgroups_len;
    char root[SCAP_MAX_PATH_SIZE+1];
    int filtered_out; 
    scap_fdinfo* fdlist; 
    uint64_t clone_ts;
    int32_t tty;
    int32_t loginuid; 
 
    UT_hash_handle hh; 
}scap_threadinfo;
 
typedef struct {
    uint64_t mount_id; 
    uint32_t dev; 
    UT_hash_handle hh; 
} scap_mountinfo;
 
typedef void (*proc_entry_callback)(void* context,
                                    scap_t* handle,
                                    int64_t tid,
                                    scap_threadinfo* tinfo,
                                    scap_fdinfo* fdinfo);
 
typedef enum {
    SCAP_MODE_NONE = 0,
    SCAP_MODE_CAPTURE,
    SCAP_MODE_LIVE,
    SCAP_MODE_NODRIVER,
} scap_mode_t;
 
typedef struct scap_open_args
{
    scap_mode_t mode;
    int fd; // If non-zero, will be used instead of fname.
    const char* fname; 
    proc_entry_callback proc_callback; 
    void* proc_callback_context; 
    bool import_users; 
    uint64_t start_offset; 
    const char *bpf_probe; 
    const char *suppressed_comms[SCAP_MAX_SUPPRESSED_COMMS]; 
                                                             // events should be returned, with a trailing NULL value.
                                                             // You can provide additional comm
                                                             // values via scap_suppress_events_comm().
    bool udig; 
}scap_open_args;
 
 
//
// The following stuff is byte aligned because we save it to disk.
//
#if defined _MSC_VER
#pragma pack(push)
#pragma pack(1)
#elif defined __sun
#pragma pack(1)
#else
#pragma pack(push, 1)
#endif
 
typedef struct _scap_machine_info
{
    uint32_t num_cpus;  
    uint64_t memory_size_bytes; 
    uint64_t max_pid; 
    char hostname[128]; 
    uint64_t reserved1; 
    uint64_t reserved2; 
    uint64_t reserved3; 
    uint64_t reserved4; 
}scap_machine_info;
 
 
#define SCAP_IPV6_ADDR_LEN 16
 
typedef enum scap_ifinfo_type
{
    SCAP_II_UNKNOWN = 0,
    SCAP_II_IPV4 = 1,
    SCAP_II_IPV6 = 2,
    SCAP_II_IPV4_NOLINKSPEED = 3,
    SCAP_II_IPV6_NOLINKSPEED = 4,
}scap_ifinfo_type;
 
typedef struct scap_ifinfo_ipv4
{
    // NB: new fields must be appended
    uint16_t type; 
    uint16_t ifnamelen;
    uint32_t addr; 
    uint32_t netmask; 
    uint32_t bcast; 
    uint64_t linkspeed; 
    char ifname[SCAP_MAX_PATH_SIZE]; 
}scap_ifinfo_ipv4;
 
typedef struct scap_ifinfo_ipv4_nolinkspeed
{
    uint16_t type;
    uint16_t ifnamelen;
    uint32_t addr;
    uint32_t netmask;
    uint32_t bcast;
    char ifname[SCAP_MAX_PATH_SIZE];
}scap_ifinfo_ipv4_nolinkspeed;
 
typedef struct scap_ifinfo_ipv6
{
    // NB: new fields must be appended
    uint16_t type;
    uint16_t ifnamelen;
    char addr[SCAP_IPV6_ADDR_LEN]; 
    char netmask[SCAP_IPV6_ADDR_LEN]; 
    char bcast[SCAP_IPV6_ADDR_LEN]; 
    uint64_t linkspeed; 
    char ifname[SCAP_MAX_PATH_SIZE]; 
}scap_ifinfo_ipv6;
 
typedef struct scap_ifinfo_ipv6_nolinkspeed
{
    uint16_t type;
    uint16_t ifnamelen;
    char addr[SCAP_IPV6_ADDR_LEN];
    char netmask[SCAP_IPV6_ADDR_LEN];
    char bcast[SCAP_IPV6_ADDR_LEN];
    char ifname[SCAP_MAX_PATH_SIZE];
}scap_ifinfo_ipv6_nolinkspeed;
 
#if defined __sun
#pragma pack()
#else
#pragma pack(pop)
#endif
 
typedef struct scap_addrlist
{
    uint32_t n_v4_addrs; 
    uint32_t n_v6_addrs; 
    uint32_t totlen; 
    scap_ifinfo_ipv4* v4list; 
    scap_ifinfo_ipv6* v6list; 
}scap_addrlist;
 
#define MAX_CREDENTIALS_STR_LEN 256
#define USERBLOCK_TYPE_USER 0
#define USERBLOCK_TYPE_GROUP 1
 
typedef struct scap_userinfo
{
    uint32_t uid; 
    uint32_t gid; 
    char name[MAX_CREDENTIALS_STR_LEN]; 
    char homedir[SCAP_MAX_PATH_SIZE]; 
    char shell[SCAP_MAX_PATH_SIZE]; 
}scap_userinfo;
 
typedef struct scap_groupinfo
{
    uint32_t gid; 
    char name[MAX_CREDENTIALS_STR_LEN]; 
}scap_groupinfo;
 
typedef struct scap_userlist
{
    uint32_t nusers; 
    uint32_t ngroups; 
    uint32_t totsavelen; 
    scap_userinfo* users;  
    scap_groupinfo* groups; 
}scap_userlist;
 
//
// Misc definitions
//
 
typedef enum scap_os_platform
{
    SCAP_PFORM_UNKNOWN = 0,
    SCAP_PFORM_LINUX_I386 = 1,
    SCAP_PFORM_LINUX_X64 = 2,
    SCAP_PFORM_WINDOWS_I386 = 3,
    SCAP_PFORM_WINDOWS_X64 = 4,
}scap_os_platform;
 
typedef enum event_direction
{
    SCAP_ED_IN = 0,
    SCAP_ED_OUT = 1
}event_direction;
 
typedef enum compression_mode
{
    SCAP_COMPRESSION_NONE = 0,
    SCAP_COMPRESSION_GZIP = 1
}compression_mode;
 
typedef enum scap_dump_flags
{
    SCAP_DF_NONE = 0,
    SCAP_DF_STATE_ONLY = 1,     
    SCAP_DF_TRACER = (1 << 1)   
}scap_dump_flags;
 
typedef struct scap_dumper scap_dumper_t;
 
struct ppm_syscall_desc {
    enum ppm_event_category category; 
    enum ppm_event_flags flags;
    char *name; 
};
 
// Structs and defines used internally
 
#define IN
#define OUT
 
//
// udig stuff
//
#define UDIG_RING_SM_FNAME "udig_buf"
#define UDIG_RING_DESCS_SM_FNAME "udig_descs"
#define UDIG_RING_SIZE (8 * 1024 * 1024)
 
#ifndef __APPLE__
struct udig_ring_buffer_status {
    volatile uint64_t m_buffer_lock;
    volatile int m_initialized;
    volatile int m_capturing_pid;
    volatile int m_stopped;
    volatile struct timespec m_last_print_time;
    struct udig_consumer_t m_consumer;
};
#endif // __APPLE__
 
typedef struct ppm_ring_buffer_info ppm_ring_buffer_info;
 
int32_t udig_alloc_ring(int* ring_fd, uint8_t** ring, uint32_t *ringsize, char *error);
int32_t udig_alloc_ring_descriptors(int* ring_descs_fd,
    struct ppm_ring_buffer_info** ring_info,
    struct udig_ring_buffer_status** ring_status,
    char *error);
void udig_free_ring(uint8_t* addr, uint32_t size);
void udig_free_ring_descriptors(uint8_t* addr);
 
// API functions
 
scap_t* scap_open_live(char *error, int32_t *rc);
 
scap_t* scap_open_offline(const char* fname, char *error, int32_t *rc);
 
scap_t* scap_open_offline_fd(int fd, char *error, int32_t *rc);
 
scap_t* scap_open(scap_open_args args, char *error, int32_t *rc);
 
void scap_close(scap_t* handle);
 
scap_os_platform scap_get_os_platform(scap_t* handle);
 
const char* scap_getlasterr(scap_t* handle);
 
uint64_t scap_max_buf_used(scap_t* handle);
 
int32_t scap_next(scap_t* handle, OUT scap_evt** pevent, OUT uint16_t* pcpuid);
 
uint32_t scap_event_getlen(scap_evt* e);
 
uint64_t scap_event_get_ts(scap_evt* e);
 
uint64_t scap_event_get_num(scap_t* handle);
 
void scap_event_reset_count(scap_t* handle);
 
const struct ppm_event_info* scap_event_getinfo(scap_evt* e);
 
uint32_t scap_event_get_dump_flags(scap_t* handle);
 
int64_t scap_get_readfile_offset(scap_t* handle);
 
scap_dumper_t* scap_dump_open(scap_t *handle, const char *fname, compression_mode compress, bool skip_proc_scan);
 
scap_dumper_t* scap_dump_open_fd(scap_t *handle, int fd, compression_mode compress, bool skip_proc_scan);
 
void scap_dump_close(scap_dumper_t *d);
 
int64_t scap_dump_get_offset(scap_dumper_t *d);
 
int64_t scap_dump_ftell(scap_dumper_t *d);
 
void scap_dump_flush(scap_dumper_t *d);
 
int32_t scap_number_of_bytes_to_write(scap_evt *e, uint16_t cpuid, int32_t* bytes);
 
int32_t scap_dump(scap_t *handle, scap_dumper_t *d, scap_evt* e, uint16_t cpuid, uint32_t flags);
 
scap_threadinfo* scap_get_proc_table(scap_t* handle);
 
int32_t scap_get_stats(scap_t* handle, OUT scap_stats* stats);
 
int32_t scap_stop_capture(scap_t* handle);
 
int32_t scap_start_capture(scap_t* handle);
 
scap_addrlist* scap_get_ifaddr_list(scap_t* handle);
 
scap_userlist* scap_get_user_list(scap_t* handle);
 
const struct ppm_event_info* scap_get_event_info_table();
 
const struct ppm_syscall_desc* scap_get_syscall_info_table();
 
const scap_machine_info* scap_get_machine_info(scap_t* handle);
 
int32_t scap_set_snaplen(scap_t* handle, uint32_t snaplen);
 
int32_t scap_clear_eventmask(scap_t* handle);
 
int32_t scap_set_eventmask(scap_t* handle, uint32_t event_id);
 
 
int32_t scap_unset_eventmask(scap_t* handle, uint32_t event_id);
 
 
const char* scap_get_host_root();
 
struct ppm_proclist_info* scap_get_threadlist(scap_t* handle);
 
const char *scap_get_bpf_probe_from_env();
 
bool scap_get_bpf_enabled(scap_t* handle);
 
int32_t scap_suppress_events_comm(scap_t* handle, const char *comm);
 
bool scap_check_suppressed_tid(scap_t *handle, int64_t tid);
 
// Non public functions
 
//
// Return the number of event capture devices that the library is handling. Each processor
// has its own event capture device.
//
uint32_t scap_get_ndevs(scap_t* handle);
 
// Retrieve a buffer of events from one of the cpus
extern int32_t scap_readbuf(scap_t* handle, uint32_t cpuid, OUT char** buf, OUT uint32_t* len);
 
#ifdef PPM_ENABLE_SENTINEL
// Get the sentinel at the beginning of the event
uint32_t scap_event_get_sentinel_begin(scap_evt* e);
#endif
 
// Get the information about a process.
// The returned pointer must be freed via scap_proc_free by the caller.
struct scap_threadinfo* scap_proc_get(scap_t* handle, int64_t tid, bool scan_sockets);
 
// Check if the given thread exists in ;proc
bool scap_is_thread_alive(scap_t* handle, int64_t pid, int64_t tid, const char* comm);
 
// like getpid() but returns the global PID even inside a container
int32_t scap_getpid_global(scap_t* handle, int64_t* pid);
 
struct scap_threadinfo *scap_proc_alloc(scap_t* handle);
void scap_proc_free(scap_t* handle, struct scap_threadinfo* procinfo);
void scap_dev_delete(scap_t* handle, scap_mountinfo* dev);
int32_t scap_stop_dropping_mode(scap_t* handle);
int32_t scap_start_dropping_mode(scap_t* handle, uint32_t sampling_ratio);
int32_t scap_enable_dynamic_snaplen(scap_t* handle);
int32_t scap_disable_dynamic_snaplen(scap_t* handle);
void scap_proc_free_table(scap_t* handle);
void scap_free_device_table(scap_t* handle);
void scap_refresh_iflist(scap_t* handle);
void scap_refresh_proc_table(scap_t* handle);
void scap_set_refresh_proc_table_when_saving(scap_t* handle, bool refresh);
uint64_t scap_ftell(scap_t *handle);
void scap_fseek(scap_t *handle, uint64_t off);
int32_t scap_enable_tracers_capture(scap_t* handle);
int32_t scap_enable_page_faults(scap_t *handle);
uint64_t scap_get_unexpected_block_readsize(scap_t* handle);
int32_t scap_proc_add(scap_t* handle, uint64_t tid, scap_threadinfo* tinfo);
int32_t scap_fd_add(scap_t *handle, scap_threadinfo* tinfo, uint64_t fd, scap_fdinfo* fdinfo);
scap_dumper_t *scap_memory_dump_open(scap_t *handle, uint8_t* targetbuf, uint64_t targetbufsize);
#ifdef USE_ZLIB
int32_t compr(uint8_t* dest, uint64_t* destlen, const uint8_t* source, uint64_t sourcelen, int level);
#endif
uint8_t* scap_get_memorydumper_curpos(scap_dumper_t *d);
int32_t scap_write_proc_fds(scap_t *handle, struct scap_threadinfo *tinfo, scap_dumper_t *d);
int32_t scap_write_proclist_header(scap_t *handle, scap_dumper_t *d, uint32_t totlen);
int32_t scap_write_proclist_trailer(scap_t *handle, scap_dumper_t *d, uint32_t totlen);
int32_t scap_write_proclist_entry(scap_t *handle, scap_dumper_t *d, struct scap_threadinfo *tinfo, uint32_t len);
// Variant of scap_write_proclist_entry where array-backed information
// about the thread is provided separate from the scap_threadinfo
// struct.
int32_t scap_write_proclist_entry_bufs(scap_t *handle, scap_dumper_t *d, struct scap_threadinfo *tinfo, uint32_t len,
                       const char *comm,
                       const char *exe,
                       const char *exepath,
                       const struct iovec *args, int argscnt,
                       const struct iovec *envs, int envscnt,
                       const char *cwd,
                       const struct iovec *cgroups, int cgroupscnt,
                       const char *root);
 
// Turn on processing only a subset syscalls. This is only appliable when scap
// is in LIVE mode.
int32_t scap_enable_simpledriver_mode(scap_t* handle);
int32_t scap_get_n_tracepoint_hit(scap_t* handle, long* ret);
#ifdef CYGWING_AGENT
typedef struct wh_t wh_t;
wh_t* scap_get_wmi_handle(scap_t* handle);
#endif
int32_t scap_set_fullcapture_port_range(scap_t* handle, uint16_t range_start, uint16_t range_end);
 
int32_t scap_set_statsd_port(scap_t* handle, uint16_t port);
 
#ifdef __cplusplus
}
#endif