file-permissions

# file-permissions

Reference guide for Unix file permission bits, octal notation, symbolic notation, and security-relevant permission combinations used by the permissions-auditor rules engine.

## Permission bit structure

Every file and directory on a Unix system has a 12-bit mode value. The three most significant bits are special bits; the remaining nine are the read/write/execute triple for owner, group, and other.

```
  4 bits special     3 bits owner    3 bits group    3 bits other
  [SUID][SGID][Sticky]  [r][w][x]       [r][w][x]       [r][w][x]
```

In octal notation each group of three bits is represented as a single digit 0-7:

```
0666  ->  ---- rw- rw- rw-   (world-readable, world-writable)
0755  ->  ---- rwx r-x r-x   (typical executable or directory)
0600  ->  ---- rw- --- ---   (owner-only credential file)
0700  ->  ---- rwx --- ---   (owner-only executable)
4755  ->  SUID rwx r-x r-x   (SUID executable)
1777  ->  Sticky rwx rwx rwx  (world-writable with sticky bit, e.g. /tmp)
```

## Bit values

### Permission bits

| Bit | Octal | Symbol | Meaning |
|-----|-------|--------|---------|
| Owner read | 0400 | r | Owner can read |
| Owner write | 0200 | w | Owner can write |
| Owner execute | 0100 | x | Owner can execute (or list directory) |
| Group read | 0040 | r | Group members can read |
| Group write | 0020 | w | Group members can write |
| Group execute | 0010 | x | Group members can execute |
| Other read | 0004 | r | All other users can read |
| Other write | 0002 | w | All other users can write |
| Other execute | 0001 | x | All other users can execute |

### Special bits

| Bit | Octal | Meaning |
|-----|-------|---------|
| SUID | 04000 | On executable: run as file owner. On directory: inherit owner (some systems). |
| SGID | 02000 | On executable: run as file group. On directory: new files inherit directory group. |
| Sticky | 01000 | On directory: only file owner or root can delete the file (used on /tmp). |

## Checking specific bits in code (TypeScript/Node.js)

```typescript
import { statSync } from 'node:fs';

const stat = statSync(path);
const mode = stat.mode;

// Check world-write bit
const isWorldWritable = (mode & 0o002) !== 0;

// Check world-read bit
const isWorldReadable = (mode & 0o004) !== 0;

// Check SUID
const hasSUID = (mode & 0o4000) !== 0;

// Check SGID
const hasSGID = (mode & 0o2000) !== 0;

// Check sticky bit
const hasSticky = (mode & 0o1000) !== 0;

// Check group-write bit
const isGroupWritable = (mode & 0o020) !== 0;

// Format as 4-digit octal string e.g. "0666"
const octal = (mode & 0o7777).toString(8).padStart(4, '0');
```

## Security-critical permission combinations

### World-writable file (critical)

```
condition:   (mode & 0o002) !== 0  AND  isFile
example:     0o666, 0o777, 0o646
risk:        Any local user or process can overwrite the file.
             For credential files: password exfiltration or injection.
fix:         chmod 600 <file>   (owner-only read/write)
             chmod 644 <file>   (owner read/write, others read-only)
```

### World-writable directory without sticky bit (high)

```
condition:   (mode & 0o002) !== 0  AND  !(mode & 0o1000)  AND  isDirectory
example:     0o777 (without sticky)
risk:        Any user can create, rename, or delete files in the directory.
             Enables symlink attacks and race conditions.
fix:         chmod 1777 <dir>   (world-writable + sticky, like /tmp)
             chmod 755 <dir>    (owner-only write)
```

### SUID binary (high)

```
condition:   (mode & 0o4000) !== 0  AND  isExecutable
example:     04755, 04711
risk:        The program runs with the file owner's privileges (often root).
             A vulnerability in the binary becomes a privilege escalation.
fix:         chmod u-s <file>   (remove SUID bit)
             Audit whether SUID is truly required for the binary.
```

### SGID binary (medium)

```
condition:   (mode & 0o2000) !== 0  AND  isExecutable
example:     02755, 02711
risk:        The program runs with the file group's privileges.
fix:         chmod g-s <file>   (remove SGID bit)
```

### Group-writable sensitive file (medium)

```
condition:   (mode & 0o020) !== 0  AND  pathMatchesSensitivePattern
example:     0o664, 0o775
patterns:    config/, secrets/, certs/, scripts/, *.env, *.pem, *.key, *.sh
risk:        Any user in the owning group can modify the file.
             For scripts: code injection or backdoor insertion.
fix:         chmod 644 <file>   (remove group-write)
             chmod 755 <file>   (for executables, remove group-write)
```

## Common secure permission values

| Mode | Symbolic | Use case |
|------|----------|----------|
| 0600 | rw------- | Credential files, SSH private keys, .env files |
| 0640 | rw-r----- | Config files readable by a specific service group |
| 0644 | rw-r--r-- | Public config files, static assets |
| 0700 | rwx------ | Private scripts, owner-only executables |
| 0750 | rwxr-x--- | Scripts that a service group needs to execute |
| 0755 | rwxr-xr-x | Public executables, web server document roots |
| 1777 | rwxrwxrwt | Shared temp directories (/tmp style) |
| 2755 | rwxr-sr-x | SGID directory (group inheritance for new files) |

## chmod command reference

```bash
# Set absolute mode
chmod 600 secrets.env
chmod 755 deploy.sh

# Remove specific bits
chmod o-w file          # remove other-write
chmod a-x file          # remove execute for all
chmod u-s binary        # remove SUID bit

# Add specific bits
chmod g+x script.sh     # add group-execute
chmod +t /shared/dir    # add sticky bit

# Recursive
chmod -R 755 public/

# Operate on multiple files via find
find . -name "*.env" | xargs chmod 600
find . -type f -perm /o+w | xargs chmod o-w
```

## Checking permissions on the command line

```bash
# Show symbolic and octal mode
ls -la file
stat -c "%a %n" file          # Linux
stat -f "%OLp %N" file        # macOS

# Find all world-writable files
find /path -type f -perm /o+w

# Find all world-writable files excluding symlinks
find /path -type f -perm /o+w ! -type l

# Find SUID binaries
find /path -type f -perm -4000

# Find files not owned by expected user
find /path ! -user www-data
```

## Node.js stat fields

`fs.stat()` returns a `Stats` object. Relevant fields for permission auditing:

| Field | Type | Description |
|-------|------|-------------|
| `mode` | number | Full 16-bit mode including file type bits |
| `uid` | number | Owner user ID |
| `gid` | number | Owner group ID |
| `size` | number | File size in bytes |

To extract only the permission bits: `stat.mode & 0o7777`.

To check if a path is a file: `stat.isFile()`.

To check if a path is a directory: `stat.isDirectory()`.

To check if a path is executable by the current process: `fs.accessSync(path, fs.constants.X_OK)`.

## Resolving uid/gid to names

Node.js does not provide a built-in uid-to-username lookup. Use the `uid-number` or `userid` package, or parse `/etc/passwd`:

```typescript
import { execSync } from 'node:child_process';

function uidToName(uid: number): string {
  try {
    return execSync(`id -nu ${uid}`, { encoding: 'utf8' }).trim();
  } catch {
    return String(uid);
  }
}

function gidToName(gid: number): string {
  try {
    return execSync(`id -ng ${gid}`, { encoding: 'utf8' }).trim();
  } catch {
    return String(gid);
  }
}
```

For performance in bulk scans, build a cache map from uid/gid to name on first lookup and reuse it throughout the scan.