# Postguard
[![Latest Version](https://img.shields.io/crates/v/postguard.svg)](https://crates.io/crates/postguard)
[![Documentation](https://docs.rs/postguard/badge.svg)](https://docs.rs/postguard)
[![Crates.io](https://img.shields.io/crates/l/postguard)](LICENSE)
Test Postgres-compatible statements against a set of CORS-like rules
## Why
Postgres has a rich `ROLE` system for managing privileges around data in a database.
But those privileges are often too permissive by default, and are difficult to restrict with by statement or function name.
`postguard` provides a `Guard` statement analyzer for protecting databases from malicious or invalid queries.
This `Guard` can be used in any Rust application that has access to statements (perhaps from untrusted sources) before they are run.
Under the hood, `postguard` uses the [`libpg_query`](https://github.com/pganalyze/libpg_query) library to parse queries down to a syntax tree
before checking the entire tree for disallowed nodes.
## Installation
Add `postguard` to your `Cargo.toml`:
```toml
[dependencies]
postguard = "0.1"
```
## Usage
```rust
use postguard::{AllowedFunctions, AllowedStatements, Command, Guard};
// If AllowedFunctions and AllowedStatements both are set to their 'All' variants
// then no parsing is done and all statements pass the guard
#[test]
fn it_does_nothing_by_default() {
Guard::new(AllowedStatements::All, AllowedFunctions::All)
.guard("create table test (id serial primary key)")
.expect("all statements are permitted by default");
}
// Statements are checked against the list of allowed statements when a 'List' variant
// is provided. Statement-checking is done recursively, so nested disallowed statements
// are also caught by the guard
#[test]
fn it_restricts_statements() {
let statement_guard = Guard::new(AllowedStatements::List(vec![Command::Select]));
statement_guard
.guard("create table test (id serial primary key)")
.expect_err("privileged statements are restricted");
statement_guard
.guard("select * from items")
.expect("select statements are permitted");
statement_guard
.guard("insert into items default values")
.expect_err("commands in top-level queries are restricted");
statement_guard
.guard("
with cte as (
insert into items default values
returning id
)
select * from cte
")
.expect_err("disallowed commands in nested queries or expressions are restricted");
}
// Functions are also guarded by name. To disallow all functions, leave the 'List' empty.
#[test]
fn it_restricts_functions() {
let statement_guard = Guard::new(
AllowedStatements::List(vec![Command::Select]),
AllowedFunctions::List(vec!["uuid_generate_v4".to_string()])
);
statement_guard
.guard("select pg_sleep(1)")
.expect_err("built-in functions and stored procs are restricted");
statement_guard
.guard("select uuid_generate_v4() as id")
.expect("allowed functions are permitted");
}
```