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 :
`usage: oputil.js mb <action> [<arguments>]
actions:
Actions:
areafix CMD1 CMD2 ... ADDR Sends an AreaFix NetMail
NetMail is sent to supplied address with the supplied command(s). Multi-part commands

223
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]
<command> [<args>]
<command> [<arguments>]
global args:
-c, --config PATH specify config path (./config/)
-n, --no-prompt assume defaults/don't prompt for input where possible
Global arguments:
-c, --config PATH Specify config path (default is ./config/)
-n, --no-prompt Assume defaults (don't prompt for input where possible)
commands:
user user utilities
config config file management
fb file base management
mb message base management
Commands:
user User management
config Configuration management
fb File base management
mb Message base management
```
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.
```
usage: oputil.js user <action> [<args>]
usage: oputil.js user <action> [<arguments>]
actions:
info USERNAME display information about a user
pw USERNAME PASSWORD set a user's password
aliases: password, passwd
rm USERNAME permanently removes user from system
aliases: remove, delete, del
rename USERNAME NEWNAME rename a user
aliases: mv
activate USERNAME set status to active
deactivate USERNAME set status to inactive
disable USERNAME set status to disabled
lock USERNAME set status to locked
group USERNAME [+|-]GROUP adds (+) or removes (-) user from a group
Actions:
info USERNAME Display information about a user
pw USERNAME PASSWORD Set a user's password
(passwd|password)
rm USERNAME Permanently removes user from system
(del|delete|remove)
rename USERNAME NEWNAME Rename a user
(mv)
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 |
@ -64,25 +98,30 @@ actions:
| `pw` | Set password | `./oputil.js user pw joeuser s3cr37` | `passwd`, `password` |
| `rm` | Removes user | `./oputil.js user del joeuser` | `remove`, `del`, `delete` |
| `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 |
| `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 |
| `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 |
#### 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
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:
new generate a new/initial configuration
cat cat current configuration to stdout
Actions:
new Generate a new / default configuration
cat args:
--no-color disable color
--no-comments strip any comments
cat Write current configuration to stdout
cat arguments:
--no-color Disable color
--no-comments Strip any comments
```
| Action | Description | Examples |
@ -94,56 +133,75 @@ cat args:
The `fb` command provides a powerful file base management interface.
```
usage: oputil.js fb <action> [<args>]
usage: oputil.js fb <action> [<arguments>]
actions:
scan AREA_TAG[@STORAGE_TAG] scan specified area
may also contain optional GLOB as last parameter,
for example: scan some_area *.zip
Actions:
scan AREA_TAG[@STORAGE_TAG] Scan specified area
info CRITERIA display information about areas and/or files
matching CRITERIA.
May contain optional GLOB as last parameter.
Example: ./oputil.js fb scan d0pew4r3z *.zip
mv SRC [SRC...] DST move entry(s) from SRC to DST
SRC: FILENAME_WC|SHA|FILE_ID|AREA_TAG[@STORAGE_TAG]
DST: AREA_TAG[@STORAGE_TAG]
info CRITERIA Display information about areas and/or files
rm SRC [SRC...] remove entry(s) from the system matching SRC
SRC: FILENAME_WC|SHA|FILE_ID|AREA_TAG[@STORAGE_TAG]
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
mv SRC [SRC...] DST Move matching entry(s)
(move)
scan args:
--tags TAG1,TAG2,... specify tag(s) to assign to discovered entries
Source may be any of the following:
- 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
other sources such as FILE_ID.DIZ. Path must point to
a valid FILES.BBS or DESCRIPT.ION file.
--update attempt to update information for existing entries
--quick perform quick scan
rm SRC [SRC...] Remove entry(s) from the system
(del|delete|remove)
info args:
--show-desc display short description, if any
Source may be any of the following:
- Filename including '*' wildcards
- SHA-1
- File ID
- Area tag with optional @storageTag suffix
remove args:
--phys-file also remove underlying physical file
desc CRITERIA Updates an file base entry's description
import-areas args:
--type TYPE sets import areas type. valid options are "zxx" or "na"
--create-dirs create backing storage directories
Launches an external editor using $VISUAL, $EDITOR, or vim/notepad.
general information:
AREA_TAG[@STORAGE_TAG] can specify an area tag and optionally, a storage specific tag
example: retro@bbs
import-areas FILEGATE.ZXX Import file base areas using FileGate RAID type format
CRITERIA file base entry criteria. in general, can be AREA_TAG, SHA,
FILE_ID, or FILENAME_WC.
scan arguments:
--tags TAG1,TAG2,... Specify hashtag(s) to assign to discovered entries
FILENAME_WC filename with * and ? wildcard support. may match 0:n entries
SHA full or partial SHA-256
FILE_ID a file identifier. see file.sqlite3
--desc-file [PATH] Prefer file descriptions from supplied input file
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
@ -152,7 +210,8 @@ The `scan` action can (re)scan a file area for new entries as well as update (`-
##### Examples
Performing a quick scan of a specific area's storage location ("retro_warez", "retro_warez_games) matching only *.zip extensions:
```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".
@ -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:
```
usage: oputil.js mb <action> [<args>]
usage: oputil.js mb <action> [<arguments>]
actions:
areafix CMD1 CMD2 ... ADDR sends an AreaFix NetMail to ADDR with the supplied command(s)
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
Actions:
areafix CMD1 CMD2 ... ADDR Sends an AreaFix NetMail
import-areas args:
--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 comma separated uplinks
--type TYPE area import type. valid options are "bbs" and "na"
NetMail is sent to supplied address with the supplied command(s). Multi-part commands
such as "%COMPRESS ZIP" should be quoted.
import-areas PATH Import areas using FidoNet *.NA or AREAS.BBS file
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 |

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 |
| 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. |
| 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 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
}
]
// ...
}
```