Version 4.2.3

• Security Levels
• Setting Security Level
• Function Safety Categories
• Permission Matrix
• External Extension Security
  • 1 Extension Loading Gate (SECOP_EXT_LOAD)
  • 2 Security Pinning (Minimum-Floor Model)
  • 3 Path Validation
• Use Cases
  • Running student homework (EDUCATIONAL)
  • Online BASIC playground (PARANOID)
  • Extension development (SAFE)
  • Batch processing (STANDARD)
  • Game toolkit (SAFE with extensions)
• Security Errors
• Implementation Notes
• Best Practices

BASIC++ includes a 6-level security model that restricts what programs can do. This is essential when running untrusted BASIC code, educational environments, and extension/plugin development.

Security levels can only go UP, never down (one-way ratchet). Once you set SECURITY SAFE, you cannot return to SECURITY OPEN within the same session. Only a NEW or direct-mode command at level 0 can lower it.

BASIC++ uses named security levels. Numbers are supported but the named form is preferred.

SECURITY OPEN              ' Level 0 - unrestricted
SECURITY SAFE              ' Level 1 - memory protected
SECURITY STANDARD          ' Level 2 - sandboxed I/O
SECURITY EDUCATIONAL       ' Level 3 - classroom mode
SECURITY RESTRICTED        ' Level 4 - minimal I/O
SECURITY PARANOID          ' Level 5 - pure computation

SECURITY 0                 ' Numeric form (discouraged)
SECURITY 1                 ' Use named form instead

Use named form (SECURITY SAFE) rather than numeric (SECURITY 1).

Security can be set in direct mode or in a program:

10 SECURITY SAFE
20 ' Rest of program runs with memory protection

Every built-in function has a safety classification:

Examples: FSAFE_PURE: ABS, LEN, LEFT$, MID$, SIN, COS, VAL, STR$ FSAFE_STATE: RND, FRE, TIMER, POS, CSRLIN FSAFE_IO: SHELL$, ENVIRON$, OPEN, CLOSE FSAFE_SYSTEM: PEEK, POKE, INP, OUT, DEF USR

What's allowed at each security level:

Key: Y=allowed, -=blocked, CWD=current directory only, Lim=limited

External code loading (LOAD FUNCTION, LOAD LIBRARY, LOAD FEATURE, LOAD PLUGIN) is controlled by the SECOP_EXT_LOAD permission:

OPEN: Allowed SAFE: Allowed STANDARD: Allowed EDUCATIONAL: BLOCKED (no external code in classrooms) RESTRICTED: BLOCKED PARANOID: BLOCKED (no external anything)

Every external extension declares a required security level:

External functions: required_level in BppExtFunc struct External libraries: REM @SECURITY tag in .lib file External features: SECURITY in .spec file External plugins: security: in plugin.yaml manifest External modules: required_level in ModuleInfo struct

Pinning uses a MINIMUM-FLOOR model:

An extension pinned to SAFE requires the interpreter to be at SAFE or higher. It works at SAFE, STANDARD, EDUCATIONAL, RESTRICTED (subject to SECOP_EXT_LOAD gate).

An extension pinned to STANDARD requires STANDARD or higher.

OPEN (level 0) is LESS secure than SAFE (level 1), so an extension pinned to SAFE will NOT load at OPEN.

PARANOID (level 5) blocks ALL external extensions regardless of pinning.

Unpinned extensions (SEC_COUNT) work at any level that passes the SECOP_EXT_LOAD gate.

All external code paths are validated:

Allowed: CWD-relative paths only Allowed: .dll .so .lib .bpl .bpp .bas .spec .yaml extensions Blocked: Absolute paths (C:, /, \) Blocked: Path traversal (..) Blocked: Unrecognized extensions (.exe .bat .cmd .py etc)

10 SECURITY EDUCATIONAL
20 ' Students can compute, use graphics, but
30 ' cannot load external code or delete files
40 CHAIN "student_program.bas"

SECURITY PARANOID
' Pure computation only -- safe for web execution
' Only math, strings, and flow control

10 SECURITY SAFE
20 ' Extensions pinned to SAFE will load here
30 LOAD FUNCTION "myext.dll"
40 PRINT MYEXT(42)

10 SECURITY STANDARD
20 ' Can do file I/O in current dir
30 ' No SHELL, no EXEC, no KILL
40 OPEN "data.txt" FOR INPUT AS #1
50 ' ...process data...
60 CLOSE #1

10 SECURITY SAFE
20 LOAD PLUGIN "gamedev"
30 ' Plugin loads at SAFE because SAFE >= SAFE
40 ' Graphics, sound, input all available

When a blocked operation is attempted:

SORRY? Security: shell access not permitted at level STANDARD in line 30

This triggers error code 70. Catch with ON ERROR GOTO:

10 ON ERROR GOTO 100
20 SECURITY STANDARD
30 SHELL "dir"              ' Blocked!
40 END
100 IF ERR = 70 THEN PRINT "Not allowed!" : RESUME NEXT

The security system is implemented in security.c / security.h.

Key components:

• Permission matrix: static 2D array [6][19] (levels x operations)
• security_check(): operation-level gate
• security_check_pinned_level(): minimum-floor pinning
• security_check_path(): path traversal/extension validation
• security_check_mem(): hardware memory bounds
• security_check_port(): port I/O gate (explicit port whitelist)

The 19 SecOperations (columns in the permission matrix) are:

For C module authors: set the appropriate FSAFE_* level on your registered functions. Set required_level on your ModuleInfo to declare the minimum security level your module requires.

• Set security level EARLY in your program
• Use the LOWEST level that meets your needs
• Use named levels (SECURITY SAFE) not numbers (SECURITY 1)
• Remember: level can go UP but not DOWN
• Test at each security level to verify behavior
• Use ON ERROR GOTO to handle permission errors gracefully
• Pin external extensions to SAFE (the recommended default)
• For classroom use, EDUCATIONAL blocks external code loading
• For maximum safety, combine SECURITY PARANOID with a restricted dialect (e.g., Tiny BASIC)