~egtann/sum

3ad06d2ce33f600fad1f43c140160a67ade13a55 — Evan Tann 4 months ago 37470e1
add sf.conf.5 man page
2 files changed, 145 insertions(+), 5 deletions(-)

M man/man1/sf.1
A man/man5/sf.conf.5
M man/man1/sf.1 => man/man1/sf.1 +5 -5
@@ 18,7 18,7 @@
.Sh DESCRIPTION
The
.Nm
utility enforces privileges in your sql database according to
utility applies privileges in your sql database according to
.Xr sf.conf 5 .
It wipes existing privileges and re-applies new ones, whitelisting and
blacklisting access to databases, tables, statements, and columns on a per-user


@@ 27,19 27,19 @@ basis.
is declarative; it will produce the same privileges on each run and is safe to
run multiple times.
.Pp
Only MySQL v5.7 is currently supported. MariaDB is not compatible.
Only MySQL v5.7 is currently supported.  MariaDB is not compatible.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl d
Dry run. Print JSON of all denied columns to stdout without modifying the
Dry run.  Print JSON of all denied columns to stdout without modifying the
database directly.
.It Fl f Ar file
Update the current privileges with the rules contained in
.Ar file .
This
.Ar file
may contain macros, tables, and privilege rules.
may contain macros and privilege rules.
.It Fl p Ar password
The password for the SQL
.Ar user .


@@ 59,7 59,7 @@ SQL server name for TLS.
.Pp
.Bl -tag -width Ds
.It Fl u Ar user
User in the SQL database. Must have the GRANT privilege.
User in the SQL database.  Must have the GRANT privilege.
.El
.Sh EXIT STATUS
.Ex -std

A man/man5/sf.conf.5 => man/man5/sf.conf.5 +140 -0
@@ 0,0 1,140 @@
.Dd $Mdocdate$
.Dt SF.CONF 5
.Os
.Sh NAME
.Nm sf.conf
.Nd sf configuration file
.Sh DESCRIPTION
The
.Xr sf 1
utility applies privileges in your sql database according to rules or
definitions specified in
.Nm .
.Pp
This is an overview of the sections in this manual page:
.Bl -inset
.It Sx RULES
provides rules for allowing and denying access to data.
.It Sx STATEMENTS
provides a complete list of allowed statements in rules.
.It Sx EXAMPLES
provides some example rulesets.
.El
.Pp
The current line can be extended over multiple lines using a backslash
.Pq Sq \e .
Comments can be put at the start of lines in the file using a hash mark
.Pq Sq # ,
and extend to the end of the current line.
.Pp
Macros can be defined that will later by expanded in context.  Macro names must
start with a letter, digit, or underscore and may contain any of those
characters.
Macro names may not be reserved words (for example
.Ic deny ,
.Cm all ,
.Cm any ) .
.Pp
The top-most rule in
.Nm
must be
.Ic deny Cm all .
This will ensure that the same privileges are applied on each run, allowing you
to run
.Xr sf 1
multiple times and get the same behavior on each run.  This requirement is
enforced by
.Xr sf 1 .
.Sh RULES
.Xr sf 1
has the ability to
.Ic deny
and
.Ic allow
users access to data in a SQL server.  Filter rules determine which of these
actions are taken; filter parameters specify the users, databases, tables,
statements and columns to which a rule applies.
.Pp
The rules are applied in sequential order, from first to last.  If a later rule
overrides an earlier rule, the last rule's behavior will apply.
.Pp
Most parameters are optional.  If a parameter is specified, the rule only
applies to that user, database, table, statement, or column.
.Pp
The following actions can be used in the filter:
.Bl -tag -width Ds
.It Cm deny Pq Cm all | Ar user
The access is denied across all databases for the user.
.It Cm allow Pq Cm all | Ar user
The access is allowed across all databases for the user.
.It Cm db Pq Cm any | Cm Ar database
Restrict or allow access to a database.
.It Cm table Pq Cm any | Cm Ar table
Restrict or allow access to a table.
.It Cm statement Pq Cm any | Cm Ar statement
Restrict or allow access to a statement such as
.Cm select ,
.Cm insert , No or
.Cm alter .
.It Cm column Pq Cm any | Ar column
Restrict or allow access to a column.  Removing the column definition from the
rule is equivalent to
.Cm column Cm any .
.Sh STATEMENTS
.Pp
Any of the following statements may be used in rules following the
.Cm statement
directive:
.Bd -literal -offset indent
alter
create
delete
drop
event
execute
file
index
insert
process
proxy
references
reload
select
shutdown
super
trigger
update
usage
.Sh EXAMPLES
In this example, we use macros to store variables and lists which will be
replaced or expanded at runtime.
.Bd -literal -offset indent
read  = { bob jim }
write = _dashboard
crud  = { select insert update delete }

deny all
allow root

allow $read db any table any statement select
deny $read db dashboard table admins statement any \e
	column password
deny $read db dashboard table { password_resets oauth_tokens }
allow $write db any table any statement $crud
.Ed
.Pp
First we
.Cm deny all
to reset privileges in the database, then we selectively allow users to access
it.  The root user is given full privileges, and since it does not have any
deny rules apply to it in the ruleset, it is also given the
.Cm grant option .
.Pp
The users bob and jim will each have access to run select queries across any
database and table, but we specifically deny access to the password column in
the admins table and the entirety of the password_resets and oauth_tokens
tables.  The user _dashboard will have privileges to run select, insert,
update, and delete throughout the database.  We use \e to extend our rule onto
the next line.
.Sh SEE ALSO
.Xr sf 1