Permalink
Fetching contributors…
Cannot retrieve contributors at this time
978 lines (842 sloc) 33.6 KB
/**
* Copyright (c) 2014-present, Facebook, Inc.
* All rights reserved.
*
* This source code is licensed under both the Apache 2.0 license (found in the
* LICENSE file in the root directory of this source tree) and the GPLv2 (found
* in the COPYING file in the root directory of this source tree).
* You may select, at your option, one of the above-listed licenses.
*/
#pragma once
#include <map>
#include <set>
#include <unordered_map>
#include <unordered_set>
#include <utility>
#include <vector>
#ifdef WIN32
#ifndef NOMINMAX
#define NOMINMAX
#endif
#endif
#include <boost/core/ignore_unused.hpp>
#include <boost/coroutine2/coroutine.hpp>
#include <boost/optional.hpp>
#include <osquery/core.h>
#include <osquery/plugin.h>
#include <osquery/query.h>
/// Allow Tables to use "tracked" deprecated OS APIs.
#define OSQUERY_USE_DEPRECATED(expr) \
do { \
_Pragma("clang diagnostic push") _Pragma( \
"clang diagnostic ignored \"-Wdeprecated-declarations\"")(expr); \
_Pragma("clang diagnostic pop") \
} while (0)
namespace osquery {
class Status;
/**
* @brief osquery does not yet use a NULL type.
*
* If a column type is non-TEXT a NULL is defined as an empty result. The APIs
* may later define an explicit control set that is opaque to the table
* implementation.
*/
#define SQL_NULL_RESULT ""
/**
* @brief The SQLite type affinities are available as macros
*
* Type affinities: TEXT, INTEGER, BIGINT
*
* You can represent any data that can be lexically casted to a string.
* Using the type affinity names helps table developers understand the data
* types they are storing, and more importantly how they are treated at query
* time.
*/
template <typename Type>
inline std::string __sqliteField(const Type& source) noexcept {
return std::to_string(source);
}
template <size_t N>
inline std::string __sqliteField(const char (&source)[N]) noexcept {
return std::string(source, N - 1U);
}
template <size_t N>
inline std::string __sqliteField(const unsigned char (&source)[N]) noexcept {
return std::string(reinterpret_cast<const char*>(source), N - 1U);
}
inline std::string __sqliteField(const char* source) noexcept {
return std::string(source);
}
inline std::string __sqliteField(char* const source) noexcept {
return std::string(source);
}
inline std::string __sqliteField(const unsigned char* source) noexcept {
return std::string(reinterpret_cast<const char*>(source));
}
inline std::string __sqliteField(unsigned char* const source) noexcept {
return std::string(reinterpret_cast<char* const>(source));
}
inline std::string __sqliteField(const std::string& source) noexcept {
return source;
}
#ifdef WIN32
// TEXT is also defined in windows.h, we should not re-define it
#define SQL_TEXT(x) __sqliteField(x)
#else
#define SQL_TEXT(x) __sqliteField(x)
#define TEXT(x) __sqliteField(x)
#endif
/// See the affinity type documentation for TEXT.
#define INTEGER(x) __sqliteField(x)
/// See the affinity type documentation for TEXT.
#define BIGINT(x) __sqliteField(x)
/// See the affinity type documentation for TEXT.
#define UNSIGNED_BIGINT(x) __sqliteField(x)
/// See the affinity type documentation for TEXT.
#define DOUBLE(x) __sqliteField(x)
/**
* @brief The SQLite type affinities as represented as implementation literals.
*
* Type affinities: TEXT=std::string, INTEGER=int, BIGINT=long long int
*
* Just as the SQLite data is represented as lexically casted strings, as table
* may make use of the implementation language literals.
*/
#define TEXT_LITERAL std::string
/// See the literal type documentation for TEXT_LITERAL.
#define INTEGER_LITERAL int
/// See the literal type documentation for TEXT_LITERAL.
#define BIGINT_LITERAL int64_t
/// See the literal type documentation for TEXT_LITERAL.
#define UNSIGNED_BIGINT_LITERAL uint64_t
/// See the literal type documentation for TEXT_LITERAL.
#define DOUBLE_LITERAL double
enum ColumnType {
UNKNOWN_TYPE = 0,
TEXT_TYPE,
INTEGER_TYPE,
BIGINT_TYPE,
UNSIGNED_BIGINT_TYPE,
DOUBLE_TYPE,
BLOB_TYPE,
};
/// Map of type constant to the SQLite string-name representation.
extern const std::map<ColumnType, std::string> kColumnTypeNames;
/**
* @brief A ConstraintOperator is applied in an query predicate.
*
* If the query contains a join or where clause with a constraint operator and
* expression the table generator may limit the data appropriately.
*/
enum ConstraintOperator : unsigned char {
EQUALS = 2,
GREATER_THAN = 4,
LESS_THAN_OR_EQUALS = 8,
LESS_THAN = 16,
GREATER_THAN_OR_EQUALS = 32,
MATCH = 64,
LIKE = 65,
GLOB = 66,
REGEXP = 67,
UNIQUE = 1,
};
/// Type for flags for what constraint operators are admissible.
using ConstraintOperatorFlag = unsigned char;
/// Flag for any operator type.
#define ANY_OP 0xFFU
/**
* @brief A Constraint is an operator and expression.
*
* The constraint is applied to columns which have literal and affinity types.
*/
struct Constraint {
unsigned char op;
std::string expr;
/// Construct a Constraint with the most-basic information, the operator.
explicit Constraint(unsigned char _op) {
op = _op;
}
// A constraint list in a context knows only the operator at creation.
explicit Constraint(unsigned char _op, std::string _expr)
: op(_op), expr(std::move(_expr)) {}
};
/*
* @brief Column options allow for more-complicated modeling of concepts.
*
* To accommodate the oddities of operating system concepts we make use of
* simple SQLite abstractions like indexs/keys and foreign keys, we also
* allow for optimizing based on query constraints (WHERE).
*
* There are several 'complications' where the default table filter (SELECT)
* behavior attempts to mimic reality. Browser plugins or shell history are
* good examples, a SELECT without using a WHERE returns the plugins or
* history as it applies to the user running the query. If osquery is meant
* to be a daemon with absolute visibility this introduces an abnormality,
* as the expected result will only include the superuser's view, even if
* the superuser can view everything if they intended.
*
* The solution is to explicitly ask for everything, by joining against the
* users table. This options structure will allow the table implementations
* to communicate these subtleties to the user.
*/
enum class ColumnOptions {
/// Default/no options.
DEFAULT = 0,
/// Treat this column as a primary key.
INDEX = 1,
/// This column MUST be included in the query predicate.
REQUIRED = 2,
/*
* @brief This column is used to generate additional information.
*
* If this column is included in the query predicate, the table will generate
* additional information. Consider the browser_plugins or shell history
* tables: by default they list the plugins or history relative to the user
* running the query. However, if the calling query specifies a UID explicitly
* in the predicate, the meaning of the table changes and results for that
* user are returned instead.
*/
ADDITIONAL = 4,
/*
* @brief This column can be used to optimize the query.
*
* If this column is included in the query predicate, the table will generate
* optimized information. Consider the system_controls table, a default filter
* without a query predicate lists all of the keys. When a specific domain is
* included in the predicate then the table will only issue syscalls/lookups
* for that domain, greatly optimizing the time and utilization.
*
* This optimization does not mean the column is an index.
*/
OPTIMIZED = 8,
/// This column should be hidden from '*'' selects.
HIDDEN = 16,
};
/// Treat column options as a set of flags.
inline ColumnOptions operator|(ColumnOptions a, ColumnOptions b) {
return static_cast<ColumnOptions>(static_cast<int>(a) | static_cast<int>(b));
}
/// Treat column options as a set of flags.
inline size_t operator&(ColumnOptions a, ColumnOptions b) {
return static_cast<size_t>(a) & static_cast<size_t>(b);
}
/**
* @brief Attributes about a Table implementation.
*/
enum class TableAttributes {
/// Default no-op attribute.
NONE = 0,
/// This table is a 'utility' and is always available locally.
UTILITY = 1,
/// The results from this table may be cached within a schedule.
CACHEABLE = 2,
/// The results are backed by a set time-indexed, always growing, events.
EVENT_BASED = 4,
/// This table inspect items relative to each user, a JOIN may be required.
USER_BASED = 8,
/// This table's data requires an osquery kernel extension/module.
KERNEL_REQUIRED = 16,
};
/// Treat table attributes as a set of flags.
inline TableAttributes operator|(TableAttributes a, TableAttributes b) {
return static_cast<TableAttributes>(static_cast<int>(a) |
static_cast<int>(b));
}
/// Treat column options as a set of flags.
inline size_t operator&(TableAttributes a, TableAttributes b) {
return static_cast<size_t>(a) & static_cast<size_t>(b);
}
/// Helper alias for TablePlugin names.
using TableName = std::string;
/// Alias for an ordered list of column name and corresponding SQL type.
using TableColumns =
std::vector<std::tuple<std::string, ColumnType, ColumnOptions>>;
/// Alias for map of column alias sets.
using ColumnAliasSet = std::map<std::string, std::set<std::string>>;
/// Forward declaration of QueryContext for ConstraintList relationships.
struct QueryContext;
/**
* @brief A ConstraintList is a set of constraints for a column. This list
* should be mapped to a left-hand-side column name.
*
* The table generator does not need to check each constraint in its decision
* logic. The common constraint checking patterns (match) are abstracted using
* simple logic operators on the literal SQLite affinity types.
*
* A constraint list supports all AS_LITERAL types, and all ConstraintOperators.
*/
struct ConstraintList : private boost::noncopyable {
public:
/// The SQLite affinity type.
ColumnType affinity{TEXT_TYPE};
/**
* @brief Check if an expression matches the query constraints.
*
* Evaluate ALL constraints in this ConstraintList against the string
* expression. The affinity of the constraint will be used as the affinite
* and lexical type of the expression and set of constraint expressions.
* If there are no predicate constraints in this list, all expression will
* match. Constraints are limitations.
*
* @param expr a SQL type expression of the column literal type to check.
* @return If the expression matched all constraints.
*/
bool matches(const std::string& expr) const;
/**
* @brief Check if an expression matches the query constraints.
*
* `matches` also supports the set of SQL affinite types.
* The expression expr will be evaluated as a string and compared using
* the affinity of the constraint.
*
* @param expr a SQL type expression of the column literal type to check.
* @return If the expression matched all constraints.
*/
template <typename T>
bool matches(const T& expr) const {
return matches(SQL_TEXT(expr));
}
/**
* @brief Check and return if there are constraints on this column.
*
* A ConstraintList is used in a ConstraintMap with a column name as the
* map index. Tables that act on optional constraints should check if any
* constraint was provided. The ops parameter serves to specify which
* operators we want to check existence for.
*
* @param ops (Optional: default ANY_OP) The operators types to look for.
* @return true if any constraint exists.
*/
bool exists(ConstraintOperatorFlag ops = ANY_OP) const;
/**
* @brief Check if a constraint exists AND matches the type expression.
*
* See ConstraintList::exists and ConstraintList::matches.
*
* @param expr The expression to match.
* @return true if any constraint exists AND matches the type expression.
*/
template <typename T>
bool existsAndMatches(const T& expr) const {
return (exists() && matches(expr));
}
/**
* @brief Check if a constraint is missing or matches a type expression.
*
* A ConstraintList is used in a ConstraintMap with a column name as the
* map index. Tables that act on required constraints can make decisions
* on missing constraints or a constraint match.
*
* @param expr The expression to match.
* @return true if constraint is missing or matches the type expression.
*/
template <typename T>
bool notExistsOrMatches(const T& expr) const {
return (!exists() || matches(expr));
}
/**
* @brief Helper templated function for ConstraintList::matches.
*/
template <typename T>
bool literal_matches(const T& base_expr) const;
/**
* @brief Get all expressions for a given ConstraintOperator.
*
* This is most useful if the table generation requires as column.
* The generator may `getAll(EQUALS)` then iterate.
*
* @param op the ConstraintOperator.
* @return A list of TEXT%-represented types matching the operator.
*/
std::set<std::string> getAll(ConstraintOperator op) const;
/// See ConstraintList::getAll, but as a selected literal type.
template <typename T>
std::set<T> getAll(ConstraintOperator op) const;
/// Constraint list accessor, types and operator.
const std::vector<struct Constraint>& getAll() const {
return constraints_;
}
/**
* @brief Add a new Constraint to the list of constraints.
*
* @param constraint a new operator/expression to constrain.
*/
void add(const struct Constraint& constraint) {
constraints_.push_back(constraint);
}
/**
* @brief Serialize a ConstraintList into a property tree.
*
* The property tree will use the format:
* {
* "affinity": affinity,
* "list": [
* {"op": op, "expr": expr}, ...
* ]
* }
*/
void serialize(JSON& doc, rapidjson::Value& obj) const;
/// See ConstraintList::unserialize.
void deserialize(const rapidjson::Value& obj);
private:
/// List of constraint operator/expressions.
std::vector<struct Constraint> constraints_;
private:
friend struct QueryContext;
private:
FRIEND_TEST(TablesTests, test_constraint_list);
};
/// Pass a constraint map to the query request.
using ConstraintMap = std::map<std::string, struct ConstraintList>;
/// Populate a constraint list from a query's parsed predicate.
using ConstraintSet = std::vector<std::pair<std::string, struct Constraint>>;
/// Keep track of which columns are used
using UsedColumns = std::unordered_set<std::string>;
/**
* @brief osquery table content descriptor.
*
* This object is the abstracted SQLite database's virtual table descriptor.
* When the virtual table is created/connected the name and columns are
* retrieved via the TablePlugin call API. The details are kept in this context
* so column parsing and row walking does not require additional Registry calls.
*
* When tables are accessed as the result of an SQL statement a QueryContext is
* created to represent metadata that can be used by the virtual table
* implementation code. Thus the code that generates rows can choose to emit
* additional data, restrict based on constraints, or potentially yield from
* a cache or choose not to generate certain columns.
*/
struct VirtualTableContent {
/// Friendly name for the table.
TableName name;
/// Table column structure, retrieved once via the TablePlugin call API.
TableColumns columns;
/// Attributes are copied into the content such that they can be quickly
/// passed to the SQL and optional Query for inspection.
TableAttributes attributes{TableAttributes::NONE};
/**
* @brief Table column aliases structure.
*
* This is used within xColumn to move content from special HIDDEN columns
* that act as aliases. If these columns are requested the content is moved
* from the new non-deprecated name.
*/
std::map<std::string, size_t> aliases;
/// Transient set of virtual table access constraints.
std::unordered_map<size_t, ConstraintSet> constraints;
/// Transient set of virtual table used columns
std::unordered_map<size_t, UsedColumns> colsUsed;
/*
* @brief A table implementation specific query result cache.
*
* Virtual tables may 'cache' information between filter requests. This is
* intended to provide optimization for very latent/expensive tables where
* complex joins may result in duplicate filter requests.
*
* The cache is implemented as a map of row data. The cache concept
* should utilize a primary key as an index, and may store arbitrary data.
* More intense caching may use the backing store though the general database
* set and get calls.
*
* The in-memory, non-backing store, cache is expired after each query run.
* This caching does not affect or use the schedule results cache.
*/
std::map<std::string, Row> cache;
};
using RowGenerator = boost::coroutines2::coroutine<Row&>;
using RowYield = RowGenerator::push_type;
/**
* @brief A QueryContext is provided to every table generator for optimization
* on query components like predicate constraints and limits.
*/
struct QueryContext : private only_movable {
/// Construct a context without cache support.
QueryContext() : table_(new VirtualTableContent()) {}
/// If the context was created without content, it is ephemeral.
~QueryContext() {
if (!enable_cache_ && table_ != nullptr) {
delete table_;
table_ = nullptr;
}
}
/// Construct a context and set the table content for caching.
explicit QueryContext(VirtualTableContent* content)
: enable_cache_(true), table_(content) {}
/// Allow moving.
QueryContext(QueryContext&&) = default;
/// Allow move assignment.
QueryContext& operator=(QueryContext&&) = delete;
/**
* @brief Check if a constraint exists for a given column operator pair.
*
* Operator and expression existence and matching occurs on the constraint
* list for a given column name. The query context maintains a map of columns
* to potentially empty constraint lists. Check if a constraint exists with
* any operator or for a specific operator, usually equality (EQUALS).
*
* @param column The name of a column within this table.
* @param op Check for a specific constraint operator (default EQUALS).
* @return true if a constraint exists, false if empty or no operator match.
*/
bool hasConstraint(const std::string& column,
ConstraintOperator op = EQUALS) const;
/**
* @brief Apply a predicate function to each expression in a constraint list.
*
* Most constraint sets are use to extract expressions or perform a row
* generation for each expressions (given an operator).
*
* This prevents the caller (table implementation) from extracting the set
* and iterating separately on potentially duplicate and copied data. The
* predicate function is provided two arguments:
* - An iterating reference to each expression for the given operator.
*
* @param column The name of a column within this table.
* @param op The comparison or expression operator (e.g., EQUALS).
* @param predicate A predicate receiving each expression.
*/
template <typename T>
void iteritems(const std::string& column,
ConstraintOperator op,
std::function<void(const T& expr)> predicate) const {
if (constraints.count(column) > 0) {
const auto& list = constraints.at(column);
if (list.affinity == TEXT_TYPE) {
for (const auto& constraint : list.constraints_) {
if (constraint.op == op) {
predicate(constraint.expr);
}
}
} else {
auto constraint_set = list.getAll<T>(op);
for (const auto& constraint : constraint_set) {
predicate(constraint);
}
}
}
}
/// Helper for string type (most all types are TEXT/VARCHAR).
void iteritems(const std::string& column,
ConstraintOperator op,
std::function<void(const std::string& expr)> predicate) const {
return iteritems<std::string>(column, op, std::move(predicate));
}
/**
* @brief Expand a list of constraints into a set of values.
*
* This is most (perhaps only) helpful with filesystem globbing inputs.
* The requirement is a constraint column that takes an expandable input.
* This method will accept an expand predicate and return the aggregate set of
* expanded items.
*
* In the future this will be a templated type that restricts the predicate
* to act on the column's affinite type and returns a similar-typed set.
*
* @param column The name of a column within this table.
* @param op An operator to retrieve from the constraint list.
* @param output The output parameter, a set of expanded values.
* @param predicate A predicate lambda to apply to each constraint.
* @return An aggregate status, if any predicate fails the operation fails.
*/
Status expandConstraints(
const std::string& column,
ConstraintOperator op,
std::set<std::string>& output,
std::function<Status(const std::string& constraint,
std::set<std::string>& output)> predicate);
/// Check if the given column is used by the query
bool isColumnUsed(const std::string& colName) const;
/// Check if any of the given columns is used by the query
bool isAnyColumnUsed(std::initializer_list<std::string> colNames) const;
template <typename Type>
inline void setTextColumnIfUsed(Row& r,
const std::string& colName,
const Type& value) const {
if (isColumnUsed(colName)) {
r[colName] = TEXT(value);
}
}
template <typename Type>
inline void setIntegerColumnIfUsed(Row& r,
const std::string& colName,
const Type& value) const {
if (isColumnUsed(colName)) {
r[colName] = INTEGER(value);
}
}
template <typename Type>
inline void setBigIntColumnIfUsed(Row& r,
const std::string& colName,
const Type& value) const {
if (isColumnUsed(colName)) {
r[colName] = BIGINT(value);
}
}
inline void setColumnIfUsed(Row& r,
const std::string& colName,
const std::string& value) const {
if (isColumnUsed(colName)) {
r[colName] = value;
}
}
/// Check if a table-defined index exists within the query cache.
bool isCached(const std::string& index) const;
/// Retrieve an index within the query cache.
const Row& getCache(const std::string& index);
/// Helper to retrieve a keyed element within the query cache.
const std::string& getCache(const std::string& index, const std::string& key);
/// Request the context use the warm query cache.
void useCache(bool use_cache);
/// Check if the query requested use of the warm query cache.
bool useCache() const;
/// Set the entire cache for an index.
void setCache(const std::string& index, Row _cache);
/// Helper to set a keyed element within the query cache.
void setCache(const std::string& index,
const std::string& key,
std::string _item);
/// The map of column name to constraint list.
ConstraintMap constraints;
boost::optional<UsedColumns> colsUsed;
private:
/// If false then the context is maintaining an ephemeral cache.
bool enable_cache_{false};
/// If the context is allowed to use the warm query cache.
bool use_cache_{false};
/// Persistent table content for table caching.
VirtualTableContent* table_{nullptr};
private:
friend class TablePlugin;
};
using QueryContext = struct QueryContext;
using Constraint = struct Constraint;
/**
* @brief The TablePlugin defines the name, types, and column information.
*
* To attach a virtual table create a TablePlugin subclass and register the
* virtual table name as the plugin ID. osquery will enumerate all registered
* TablePlugins and attempt to attach them to SQLite at instantiation.
*
* Note: When updating this class, be sure to update the corresponding template
* in osquery/tables/templates/default.cpp.in
*/
class TablePlugin : public Plugin {
public:
/**
* @brief Table name aliases create full-scan VIEWs for tables.
*
* Aliases allow table names to be changed/deprecated without breaking
* existing deployments and scheduled queries.
*
* @return A string vector of qtable name aliases.
*/
virtual std::vector<std::string> aliases() const {
return {};
}
/// Return the table's column name and type pairs.
virtual TableColumns columns() const {
return TableColumns();
}
/// Define a map of target columns to optional aliases.
virtual ColumnAliasSet columnAliases() const {
return ColumnAliasSet();
}
/// Return a set of attribute flags.
virtual TableAttributes attributes() const {
return TableAttributes::NONE;
}
/**
* @brief Generate a complete table representation.
*
* The TablePlugin::generate method is the most important part of the table.
* This should return a best-effort match of the expected results for a
* query. In common cases, this returns all rows for a virtual table.
* For EventSubscriber tables this will perform database lookups for events
* matching several conditions such as time within the SQL query or the last
* time the EventSubscriber was called.
*
* The context input is filled in "as best possible" by SQLite's
* virtual table APIs. In the best case this context include a limit or
* constraints organized by each possible column.
*
* @param context A query context filled in by SQLite's virtual table API.
* @return The result rows for this table, given the query context.
*/
virtual QueryData generate(QueryContext& context) {
(void)context;
return QueryData();
}
/// Callback for DELETE statements
virtual QueryData delete_(QueryContext& context,
const PluginRequest& request) {
boost::ignore_unused(context);
boost::ignore_unused(request);
return {{std::make_pair("status", "readonly")}};
}
/// Callback for INSERT statements
virtual QueryData insert(QueryContext& context,
const PluginRequest& request) {
boost::ignore_unused(context);
boost::ignore_unused(request);
return {{std::make_pair("status", "readonly")}};
}
/// Callback for UPDATE statements
virtual QueryData update(QueryContext& context,
const PluginRequest& request) {
boost::ignore_unused(context);
boost::ignore_unused(request);
return {{std::make_pair("status", "readonly")}};
}
/**
* @brief Generate a table representation by yielding each row.
*
* For tables that set generator=True in their spec's implementation, this
* generator will be bound to an asymmetric coroutine. It should call the
* provided yield function for each Row returned. Treat this like Python's
* generator-type methods where the only difference is yield is not reserved
* but rather provided with some boilerplate syntax.
*
* This implementation uses nearly %5 more cycles than the generate method
* when the table content is small (less than 100 rows) and has a disadvantage
* of not being cachable since the entire contents are not available before
* post-filter aggregations. This implementation prevents the need for
* multiple representations of table content existing simultaneously and is
* always more memory efficient. It can be more compute efficient for tables
* with over 1000 rows.
*
* @param yield a callable that takes a single Row as input.
* @param context a query context filled in by SQLite's virtual table API.
*/
virtual void generator(RowYield& yield, QueryContext& context) {
(void)yield;
(void)context;
}
/// Override and return true to use the generator and yield method.
virtual bool usesGenerator() const {
return false;
}
protected:
/// An SQL table containing the table definition/syntax.
std::string columnDefinition(bool is_extension = false) const;
/// Return the name and column pairs for attaching virtual tables.
PluginResponse routeInfo() const override;
/**
* @brief Check if there are fresh cache results for this table.
*
* Table results are considered fresh when evaluated against a given interval.
* The interval is the expected rate for which this data should be generated.
* Caching and cache freshness only applies to queries acting on tables
* within a schedule. If two queries "one" and "two" both inspect the
* table "processes" at the interval 60. The first executed will cache results
* and the second will use the cached results.
*
* Table results are not cached if a QueryContext contains constraints or
* provides HOB (hand-off blocks) to additional tables within a query.
* Currently, the query scheduler cannot communicate to table implementations.
* An interval is set globally by the scheduler and passed to the table
* implementation as a future-proof API. There is no "shortcut" for caching
* when used in external tables. A cache lookup within an extension means
* a database call API and re-serialization to the virtual table APIs. In
* practice this does not perform well and is explicitly disabled.
*
* @param interval The interval this query expects the tables results.
* @param ctx The query context.
* @return True if the cache contains fresh results, otherwise false.
*/
bool isCached(size_t interval, const QueryContext& ctx) const;
/**
* @brief Perform a database lookup of cached results and deserialize.
*
* If a query determined the table's cached results are fresh, it may ask the
* table to retrieve results from the database and deserialized them into
* table row data.
*
* @return The deserialized row data of cached results.
*/
QueryData getCache() const;
/**
* @brief Similar to getCache, stores the results from generate.
*
* Set will serialize and save the results as JSON to be retrieved later.
* It will inspect the query context, if any required/indexed/optimized or
* additional columns are used then the cache will not be saved.
*/
void setCache(size_t step,
size_t interval,
const QueryContext& ctx,
const QueryData& results);
private:
/// The last time in seconds the table data results were saved to cache.
size_t last_cached_{0};
/// The last interval in seconds when the table data was cached.
size_t last_interval_{0};
public:
/**
* @brief The scheduled interval for the executing query.
*
* Scheduled queries execute within a pseudo-mutex, and each may communicate
* their scheduled interval to internal TablePlugin implementations. If the
* table is cachable then the interval can be used to calculate freshness.
*/
static size_t kCacheInterval;
/// The schedule step, this is the current position of the schedule.
static size_t kCacheStep;
public:
/**
* @brief The registry call "router".
*
* Like all of osquery's Plugin%s, the TablePlugin uses a "call" router to
* handle requests and responses from extensions. The TablePlugin uses an
* "action" key, which can be:
* - generate: call the plugin's row generate method (defined in spec).
* - columns: return a list of column name and SQLite types.
* - definition: return an SQL statement for table creation.
*
* @param request The plugin request, must include an action key.
* @param response A plugin response, for generation this contains the rows.
*/
Status call(const PluginRequest& request, PluginResponse& response) override;
public:
/// Helper data structure transformation methods.
static void setRequestFromContext(const QueryContext& context,
PluginRequest& request);
/// Helper data structure transformation methods.
static void setContextFromRequest(const PluginRequest& request,
QueryContext& context);
public:
/**
* @brief Add a virtual table that exists in an extension.
*
* When external table plugins are registered the core will attach them
* as virtual tables to the SQL internal implementation.
*
* @param name The table name.
* @param info The route info (column name and type pairs).
*/
static Status addExternal(const std::string& name,
const PluginResponse& info);
/// Remove an extension's table from the SQL virtual database.
static void removeExternal(const std::string& name);
private:
friend class RegistryFactory;
FRIEND_TEST(VirtualTableTests, test_tableplugin_columndefinition);
FRIEND_TEST(VirtualTableTests, test_extension_tableplugin_columndefinition);
FRIEND_TEST(VirtualTableTests, test_tableplugin_statement);
FRIEND_TEST(VirtualTableTests, test_indexing_costs);
FRIEND_TEST(VirtualTableTests, test_table_results_cache);
FRIEND_TEST(VirtualTableTests, test_yield_generator);
};
/// Helper method to generate the virtual table CREATE statement.
std::string columnDefinition(const TableColumns& columns,
bool is_extension = false);
/// Helper method to generate the virtual table CREATE statement.
std::string columnDefinition(const PluginResponse& response,
bool aliases = false,
bool is_extension = false);
/// Get the string representation for an SQLite column type.
inline const std::string& columnTypeName(ColumnType type) {
return kColumnTypeNames.at(type);
}
/// Get the column type from the string representation.
ColumnType columnTypeName(const std::string& type);
} // namespace osquery