moon
/
enigma-bbs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation updates 

+ Add Security doc
* Update optuil doc
This commit is contained in:
Bryan Ashby 2019-06-14 21:43:27 -06:00
parent 2b154800c0
commit 0f68f20656
No known key found for this signature in database
GPG Key ID: B49EB437951D2542
4 changed files with 208 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
core/oputil/oputil_help.js
View File

@ -161,7 +161,7 @@ General Information:
MessageBase : MessageBase :
`usage: oputil.js mb <action> [<arguments>] `usage: oputil.js mb <action> [<arguments>]
actions: Actions:
areafix CMD1 CMD2 ... ADDR Sends an AreaFix NetMail areafix CMD1 CMD2 ... ADDR Sends an AreaFix NetMail
NetMail is sent to supplied address with the supplied command(s). Multi-part commands NetMail is sent to supplied address with the supplied command(s). Multi-part commands

225
docs/admin/oputil.md
View File

@ -9,17 +9,17 @@ Let's look the main help output as per this writing:
``` ```
usage: oputil.js [--version] [--help] usage: oputil.js [--version] [--help]
<command> [<args>] <command> [<arguments>]
global args: Global arguments:
-c, --config PATH specify config path (./config/) -c, --config PATH Specify config path (default is ./config/)
-n, --no-prompt assume defaults/don't prompt for input where possible -n, --no-prompt Assume defaults (don't prompt for input where possible)
commands: Commands:
user user utilities user User management
config config file management config Configuration management
fb file base management fb File base management
mb message base management mb Message base management
``` ```
Commands break up operations by groups: Commands break up operations by groups:
@ -41,21 +41,55 @@ Type `./oputil.js <command> --help` for additional help on a particular command.
The `user` command covers various user operations. The `user` command covers various user operations.
``` ```
usage: oputil.js user <action> [<args>] usage: oputil.js user <action> [<arguments>]
actions: Actions:
info USERNAME display information about a user info USERNAME Display information about a user
pw USERNAME PASSWORD set a user's password
aliases: password, passwd pw USERNAME PASSWORD Set a user's password
rm USERNAME permanently removes user from system (passwd|password)
aliases: remove, delete, del
rename USERNAME NEWNAME rename a user rm USERNAME Permanently removes user from system
aliases: mv (del|delete|remove)
activate USERNAME set status to active
deactivate USERNAME set status to inactive rename USERNAME NEWNAME Rename a user
disable USERNAME set status to disabled (mv)
lock USERNAME set status to locked
group USERNAME [+|-]GROUP adds (+) or removes (-) user from a group 2fa-otp USERNAME SPEC Enable 2FA/OTP for the user
(otp)
The system supports various implementations of Two Factor Authentication (2FA)
One Time Password (OTP) authentication.
Valid specs:
disable : Removes 2FA/OTP from the user
google : Google Authenticator
hotp : HMAC-Based One-Time Password Algorithm (RFC-4266)
totp : Time-Based One-Time Password Algorithm (RFC-6238)
activate USERNAME Set a user's status to "active"
deactivate USERNAME Set a user's status to "inactive"
disable USERNAME Set a user's status to "disabled"
lock USERNAME Set a user's status to "locked"
group USERNAME [+|-]GROUP Adds (+) or removes (-) user from a group
info arguments:
--security Include security information in output
2fa-otp arguments:
--qr-type TYPE Specify QR code type
Valid QR types:
ascii : Plain ASCII (default)
data : HTML data URL
img : HTML image tag
svg : SVG image
--out PATH Path to write QR code to. defaults to stdout
``` ```
| Action | Description | Examples | Aliases | | Action | Description | Examples | Aliases |
@ -64,25 +98,30 @@ actions:
| `pw` | Set password | `./oputil.js user pw joeuser s3cr37` | `passwd`, `password` | | `pw` | Set password | `./oputil.js user pw joeuser s3cr37` | `passwd`, `password` |
| `rm` | Removes user | `./oputil.js user del joeuser` | `remove`, `del`, `delete` | | `rm` | Removes user | `./oputil.js user del joeuser` | `remove`, `del`, `delete` |
| `rename` | Renames a user | `./oputil.js user rename joeuser joe` | `mv` | | `rename` | Renames a user | `./oputil.js user rename joeuser joe` | `mv` |
| `2fa-otp` | Manage 2FA/OTP for a user | `./oputil.js user 2fa-otp joeuser googleAuth` | `otp`
| `activate` | Activates user | `./oputil.js user activate joeuser` | N/A | | `activate` | Activates user | `./oputil.js user activate joeuser` | N/A |
| `deactivate` | Deactivates user | `./oputil.js user deactivate joeuser` | N/A | | `deactivate` | Deactivates user | `./oputil.js user deactivate joeuser` | N/A |
| `disable` | Disables user (user will not be able to login) | `./oputil.js user disable joeuser` | N/A | | `disable` | Disables user (user will not be able to login) | `./oputil.js user disable joeuser` | N/A |
| `lock` | Locks the user account (prevents logins) | `./oputil.js user lock joeuser` | N/A | | `lock` | Locks the user account (prevents logins) | `./oputil.js user lock joeuser` | N/A |
| `group` | Modifies users group membership | Add to group: `./oputil.js user group joeuser +derp`<br/>Remove from group: `./oputil.js user group joeuser -derp` | N/A | | `group` | Modifies users group membership | Add to group: `./oputil.js user group joeuser +derp`<br/>Remove from group: `./oputil.js user group joeuser -derp` | N/A |
#### Manage 2FA/OTP
While `oputil.js` can be used to manage a user's 2FA/OTP, it is highly recommended to require users to opt-in themselves. See [Security](/docs/configuration/security.md) for details.
## Configuration ## Configuration
The `config` command allows sysops to perform various system configuration and maintenance tasks. The `config` command allows sysops to perform various system configuration and maintenance tasks.
``` ```
usage: oputil.js config <action> [<args>] usage: oputil.js config <action> [<arguments>]
actions: Actions:
new generate a new/initial configuration new Generate a new / default configuration
cat cat current configuration to stdout
cat args: cat Write current configuration to stdout
--no-color disable color
--no-comments strip any comments cat arguments:
--no-color Disable color
--no-comments Strip any comments
``` ```
| Action | Description | Examples | | Action | Description | Examples |
@ -94,56 +133,75 @@ cat args:
The `fb` command provides a powerful file base management interface. The `fb` command provides a powerful file base management interface.
``` ```
usage: oputil.js fb <action> [<args>] usage: oputil.js fb <action> [<arguments>]
actions: Actions:
scan AREA_TAG[@STORAGE_TAG] scan specified area scan AREA_TAG[@STORAGE_TAG] Scan specified area
may also contain optional GLOB as last parameter,
for example: scan some_area *.zip
info CRITERIA display information about areas and/or files May contain optional GLOB as last parameter.
matching CRITERIA. Example: ./oputil.js fb scan d0pew4r3z *.zip
mv SRC [SRC...] DST move entry(s) from SRC to DST info CRITERIA Display information about areas and/or files
SRC: FILENAME_WC|SHA|FILE_ID|AREA_TAG[@STORAGE_TAG]
DST: AREA_TAG[@STORAGE_TAG]
rm SRC [SRC...] remove entry(s) from the system matching SRC mv SRC [SRC...] DST Move matching entry(s)
SRC: FILENAME_WC|SHA|FILE_ID|AREA_TAG[@STORAGE_TAG] (move)
desc CRITERIA sets a new file description for file base entry
matching CRITERIA. Launches an external editor using
$VISUAL, $EDITOR, or vim/notepad.
import-areas FILEGATE.ZXX import file base areas using FileGate RAID type format
scan args: Source may be any of the following:
--tags TAG1,TAG2,... specify tag(s) to assign to discovered entries - Filename including '*' wildcards
- SHA-1
- File ID
- Area tag with optional @storageTag suffix
Destination is area tag with optional @storageTag suffix
--desc-file [PATH] prefer file descriptions from supplied path over other rm SRC [SRC...] Remove entry(s) from the system
other sources such as FILE_ID.DIZ. Path must point to (del|delete|remove)
a valid FILES.BBS or DESCRIPT.ION file.
--update attempt to update information for existing entries
--quick perform quick scan
info args: Source may be any of the following:
--show-desc display short description, if any - Filename including '*' wildcards
- SHA-1
- File ID
- Area tag with optional @storageTag suffix
remove args: desc CRITERIA Updates an file base entry's description
--phys-file also remove underlying physical file
import-areas args: Launches an external editor using $VISUAL, $EDITOR, or vim/notepad.
--type TYPE sets import areas type. valid options are "zxx" or "na"
--create-dirs create backing storage directories
general information: import-areas FILEGATE.ZXX Import file base areas using FileGate RAID type format
AREA_TAG[@STORAGE_TAG] can specify an area tag and optionally, a storage specific tag
example: retro@bbs
CRITERIA file base entry criteria. in general, can be AREA_TAG, SHA, scan arguments:
FILE_ID, or FILENAME_WC. --tags TAG1,TAG2,... Specify hashtag(s) to assign to discovered entries
FILENAME_WC filename with * and ? wildcard support. may match 0:n entries --desc-file [PATH] Prefer file descriptions from supplied input file
SHA full or partial SHA-256
FILE_ID a file identifier. see file.sqlite3 If a file description can be found in the supplied input file, prefer that description
over other sources such related FILE_ID.DIZ. Path must point to a valid FILES.BBS or
DESCRIPT.ION file.
--update Attempt to update information for existing entries
--full-scan Perform a full scan (default is quick)
info arguments:
--show-desc Display short description, if any
remove arguments:
--phys-file Also remove underlying physical file
import-areas arguments:
--type TYPE Sets import areas type
Valid types are are "zxx" or "na".
--create-dirs Also create backing storage directories
General Information:
Generally an area tag can also include an optional storage tag. For example, the
area of 'bbswarez' stored using 'bbswarez_main': bbswarez@bbswarez_main
When performing an initial import of a large area or storage backing, --full-scan
is the best option. If re-scanning an area for updates a standard / quick scan is
generally good enough.
File ID's are those found in file.sqlite3.
``` ```
#### Scan File Area #### Scan File Area
@ -152,7 +210,8 @@ The `scan` action can (re)scan a file area for new entries as well as update (`-
##### Examples ##### Examples
Performing a quick scan of a specific area's storage location ("retro_warez", "retro_warez_games) matching only *.zip extensions: Performing a quick scan of a specific area's storage location ("retro_warez", "retro_warez_games) matching only *.zip extensions:
```bash ```bash
$ ./oputil.js fb scan --quick retro_warez@retro_warez_games *.zip` # note that we must quote the wildcard to prevent shell expansion
$ ./oputil.js fb scan --quick retro_warez@retro_warez_games "*.zip"`
``` ```
Update all entries in the "artscene" area supplying the file tags "artscene", and "textmode". Update all entries in the "artscene" area supplying the file tags "artscene", and "textmode".
@ -221,19 +280,23 @@ The above command will process FILEGATE.ZXX creating areas and backing directori
The `mb` command provides various Message Base related tools: The `mb` command provides various Message Base related tools:
``` ```
usage: oputil.js mb <action> [<args>] usage: oputil.js mb <action> [<arguments>]
actions: Actions:
areafix CMD1 CMD2 ... ADDR sends an AreaFix NetMail to ADDR with the supplied command(s) areafix CMD1 CMD2 ... ADDR Sends an AreaFix NetMail
one or more commands may be supplied. commands that are multi
part such as "%COMPRESS ZIP" should be quoted.
import-areas PATH import areas using fidonet *.NA or AREAS.BBS file from PATH
import-areas args: NetMail is sent to supplied address with the supplied command(s). Multi-part commands
--conf CONF_TAG conference tag in which to import areas such as "%COMPRESS ZIP" should be quoted.
--network NETWORK network name/key to associate FTN areas
--uplinks UL1,UL2,... one or more comma separated uplinks import-areas PATH Import areas using FidoNet *.NA or AREAS.BBS file
--type TYPE area import type. valid options are "bbs" and "na"
import-areas arguments:
--conf CONF_TAG Conference tag in which to import areas
--network NETWORK Network name/key to associate FTN areas
--uplinks UL1,UL2,... One or more uplinks (comma separated)
--type TYPE Area import type
Valid types are "bbs" and "na"
``` ```
| Action | Description | Examples | | Action | Description | Examples |

2
docs/configuration/acs.md
View File

@ -38,7 +38,7 @@ The following are ACS codes available as of this writing:
| AC<i>achievementCount</i> | User has >= _achievementCount_ achievements | | AC<i>achievementCount</i> | User has >= _achievementCount_ achievements |
| AP<i>achievementPoints</i> | User has >= _achievementPoints_ achievement points | | AP<i>achievementPoints</i> | User has >= _achievementPoints_ achievement points |
| AF<i>authFactor</i> | User's current *Authentication Factor* is >= _authFactor_. Authentication factor 1 refers to username + password (or PubKey) while factor 2 refers to 2FA such as One-Time-Password authentication. | | AF<i>authFactor</i> | User's current *Authentication Factor* is >= _authFactor_. Authentication factor 1 refers to username + password (or PubKey) while factor 2 refers to 2FA such as One-Time-Password authentication. |
| AR<i>authFactorReq</i> | Current users **requires** an Authentication Factor >= _authFactorReq_ | | AR<i>authFactorReq</i> | Current user **requires** an Authentication Factor >= _authFactorReq_ |
## ACS Strings ## ACS Strings
ACS strings are one or more ACS codes in addition to some basic language semantics. ACS strings are one or more ACS codes in addition to some basic language semantics.

62
docs/configuration/security.md Normal file
View File

@ -0,0 +1,62 @@
---
layout: page
title: Security
---
## Security
Unlike in the golden era of BBSing, modern Internet-connected systems are prone to hacking attempts, eavesdropping, etc. While plain-text passwords, insecure data over [Plain Old Telephone Service (POTS)](https://en.wikipedia.org/wiki/Plain_old_telephone_service), and so on was good enough then, modern systems must employ protections against attacks. ENiGMA½ comes with many security features that help keep the system and your users secure — not limited to:
* Passwords are **never** stored in plain-text, but instead are stored using [Password-Based Key Derivation Function 2 (PBKDF2)](https://en.wikipedia.org/wiki/PBKDF2). Even the system operator can _never_ know your password!
* Alternatives to insecure Telnet logins are built in: [SSH](https://en.wikipedia.org/wiki/Secure_Shell) and secure [WebSockets](https://en.wikipedia.org/wiki/WebSocket) for example.
* A built in web server with [TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security) support (aka HTTPS).
* Optional [Two-Factor Authentication (2FA)](https://en.wikipedia.org/wiki/Multi-factor_authentication) via [One-Time-Password (OTP)](https://en.wikipedia.org/wiki/One-time_password) for users, supporting [Google Authenticator](http://google-authenticator.com/), [Time-Based One-Time Password Algorithm (TOTP, RFC-6238)](https://tools.ietf.org/html/rfc6238), and [HMAC-Based One-Time Password Algorithm (HOTP, RFC-4266)](https://tools.ietf.org/html/rfc4226).
## Two-Factor Authentication via One-Time Password
Enabling Two-Factor Authentication via One-Time-Password (2FA/OTP) on an account adds an extra layer of security ("_something a user has_") in addition to their password ("_something a user knows_"). Providing 2FA/OTP to your users has some prerequisites:
* [A configured email gateway](/docs/configuration/email.md) such that the system can send out emails.
* One or more secure servers enabled such as [SSH](/docs/servers/ssh.md) or secure [WebSockets](/docs/servers/websocket.md) (that is, WebSockets over a secure connection such as TLS).
* The [web server](/docs/servers/web-server.md) enabled and exposed over TLS (HTTPS).
:information_source: For WebSockets and the web server, ENiGMA½ _may_ listen on insecure channels if behind a secure web proxy.
### User Registration Flow
Due to the nature of 2FA/OTP, even if enabled on your system, users must opt-in and enable this feature on their account. Users must also have a valid email address such that a registration link can be sent to them. To opt-in, a process similar to the following is taken:
1. Navigate to the 2FA/OTP configuration menu and switches the feature to enabled.
2. Selects the "flavor" of 2FA/OTP: Google Authenticator, TOTP, or HOTP.
3. Confirms settings by saving.
After saving, a registration link will be mailed to the user. Clicking the link provides the following:
1. A secret for manual entry into a OTP device.
2. If applicable, a scannable QR code for easy device entry (e.g. Google Authenticator)
3. A confirmation prompt in which the user must enter a OTP code. If entered correctly, this validates everything is set up properly and 2FA/OTP will be enabled for the account. Future logins will now prompt the user for their OTP after they enter their standard password.
:warning: Serving 2FA/OTP registration links over insecure (HTTP) can expose secrets intended for the user and is **highly** discouraged!
:information_source: +ops can also manually enable or disable 2FA/OTP for a user using [oputil](/docs/admin/oputil.md), but this is generally discouraged.
### ACS Checks
Various places throughout the system that implement [ACS](/docs/configuration/acs.md) can make 2FA specific checks:
* `AR#`: Current users **required** authentication factor. `AR2` for example means 2FA/OTP is required for this user.
* `AF#`: Current users **active** authentication factor. `AF2` means the user is authenticated with some sort of 2FA (such as One-Time-Password).
See [ACS](/docs/configuration/acs.md) for more information.
#### Example
The following example illustrates using an `AR` ACS check to require applicable users to go through an additional 2FA/OTP process during login:
```hjson
login: {
art: USERLOG
next: [
{
// users with AR2+ must first pass 2FA/OTP
acs: AR2
next: loginTwoFactorAuthOTP
}
{
// everyone else skips ahead
next: fullLoginSequenceLoginArt
}
]
// ...
}
```