# llms.txt

> secure-devtools — plain-shell security tools for the code you are about to run, and the machine you run it on.

secure-devtools is a collection of local security tools for macOS and Linux. They check a project folder, and the machine, for supply-chain and dev-environment attack indicators. They need no signup, account or API key, have no npm runtime dependencies, and exit non-zero on findings so they drop into dev scripts or CI.

**Current releases:** `am-i-hacked` 2.0.1, `am-i-being-recorded` 1.0.0, `secure-semgrep` 1.0.1. In the next `am-i-hacked` release: a dark-corner system scan, a Python virtualenv integrity check, and `--max-findings`.
**Website:** https://isaacbell.github.io/secure-devtools/
**Repository:** https://github.com/IsaacBell/secure-devtools
**Maintainer:** Isaac Bell — https://isaacbell.io — https://github.com/IsaacBell

## Pages on the website

Each page answers one question and states what the tools do not do. The HTML pages are the authoritative source; this file summarizes them.

Tool reference:
- [am-i-hacked](https://isaacbell.github.io/secure-devtools/tools/am-i-hacked/): every check, flag, exit code and limit
- [am-i-being-recorded](https://isaacbell.github.io/secure-devtools/tools/am-i-being-recorded/)
- [secure-semgrep](https://isaacbell.github.io/secure-devtools/tools/secure-semgrep/): bundled rules and loadouts
- [Agent skills](https://isaacbell.github.io/secure-devtools/skills/): what each skill does and when to use it

Guides:
- [How to safely inspect an untrusted repository before you run it](https://isaacbell.github.io/secure-devtools/guides/inspect-untrusted-repository/)
- [Is AI-generated code safe to run? How to check it first](https://isaacbell.github.io/secure-devtools/guides/ai-generated-code-security/)
- [How to detect malicious VS Code tasks that run when a folder opens](https://isaacbell.github.io/secure-devtools/guides/malicious-editor-config/)
- [How to catch a supply-chain attack that npm audit misses](https://isaacbell.github.io/secure-devtools/guides/supply-chain-attack-checks/)
- [How to vet an AI agent skill, plugin or MCP server before installing it](https://isaacbell.github.io/secure-devtools/guides/vet-agent-skills/)
- [How to check whether your developer machine is compromised](https://isaacbell.github.io/secure-devtools/guides/audit-developer-machine/)
- [Is this macOS login item or background item malware?](https://isaacbell.github.io/secure-devtools/guides/macos-login-items/)
- [Which browser extension is recording my screen?](https://isaacbell.github.io/secure-devtools/guides/which-extension-is-recording-my-screen/)
- [How to prevent SSRF when your server fetches a user-supplied URL](https://isaacbell.github.io/secure-devtools/guides/prevent-ssrf/)

Context:
- [am-i-hacked vs npm audit, Semgrep and antivirus](https://isaacbell.github.io/secure-devtools/compare/): what each catches and misses
- [Security, trust and threat model](https://isaacbell.github.io/secure-devtools/security/): network behavior, telemetry, testing, release process, disclosure

## Tools (apps/)

- **am-i-hacked** — scan a project folder before you open, install or run it for malicious-code indicators, and (`--system`) audit the machine for persistence, capture tools and risky AI-tool config. Run: `npx am-i-hacked` — https://github.com/IsaacBell/secure-devtools/tree/main/apps/am-i-hacked
- **am-i-being-recorded** — name the browser extension behind a screen-recording indicator, and list what else on the machine can capture you. Run: `npx am-i-being-recorded` — https://github.com/IsaacBell/secure-devtools/tree/main/apps/am-i-being-recorded
- **secure-semgrep** — a thin Semgrep CLI that runs bundled AI-agent, bash and SSRF security rules plus maintained registry loadouts (`py`, `js`, `ts`, `react`, `node`, `rust`; the bundled `ssrf` loadout is opt-in with `-L ssrf`). Needs `semgrep`. Run: `npx secure-semgrep ./src` — https://github.com/IsaacBell/secure-devtools/tree/main/apps/secure-semgrep

## Agent skills (skills/)

Install all with `npx skills add IsaacBell/secure-devtools -g`, or one with `--skill <name>`. Each skill lives at `skills/<name>/SKILL.md`.

- **quarantine-review** — inspect an untrusted repository without running any of it.
- **secure-skill-pull** — vet a skill or plugin from a URL without running its installer.
- **create-skill** — write, check and publish an agent skill.
- **skill-publish-review** — review skills before they go into a public repository.
- **ssrf-safe-fetch** — validate the URL and the resolved address before a server fetches it.
- **login-item-triage** — the manual method behind am-i-hacked's login-item signature checks.
- **jujutsu** — use the jujutsu (`jj`) version-control system.

## am-i-hacked in detail

The dark-corner system scan, the Python virtualenv integrity check and `--max-findings` below are unreleased: they ship in the next `am-i-hacked` release and are not in 2.0.1.

- **Folder scan.** Reads JS/TS, Python, Rust, Ruby, C, C++, and C# sources. Skips `node_modules` and `.git`; also reads dot-directories and tracked files that `.gitignore` matches. Detects dynamic code execution (`eval`, `new Function`), child processes, direct network module access, runtime global writes; encoded or obfuscated payloads and unusually long lines; suspicious `package.json` scripts; editor config that runs code on folder open; download-and-run commands in editor config; executable payloads disguised as assets; clipboard/keystroke/screen capture paired with an exfiltration endpoint; `.env` files in the git index; official Yarn releases verified by SHA256; Python virtualenv integrity (package RECORD hashes, unowned files, code-running `.pth` hooks). In bundled code, only high-signal patterns are reported.
- **System scan (`--system`, alias `--full-system-scan`).** Read-only, no root or sudo. Adds login persistence (launchd on macOS; systemd user units and XDG autostart on Linux) and macOS code signatures, crontab, shell startup files, user-level and managed AI-tool config, running processes, and the "dark corners" where tooling installs code outside any project. `am-i-hacked host [dir]` checks only a folder's AI-tool config.
- **Flags:** `<dir>`; `--system`/`--full-system-scan`; `--max-findings N` (folder scan, default 1000); `-v`/`--verbose`; `-h`/`--help`.
- **Suppressing a finding:** comment `am-i-hacked-ignore: <reason>` on the flagged line or the line before it; the reason is required. The old `am-i-compromised-ignore:` spelling is honored. Suppressed findings are always listed. For the system scan, allow a finding with `<id> | <reason>` in `~/.config/am-i-hacked/host-allow.txt`.
- **Exit codes:** `0` nothing found; `1` findings to review or a missing requirement; `2` usage error.
- **Limitations (state these):** it looks for warning signs, is **not antivirus**, and does not look up known viruses. A clean result does **not** prove the code or machine is safe. Some checks flag ordinary code such as `eval`.

## CI usage

A GitHub Actions job on `ubuntu-latest`. The runner has bash, jq and npx; ripgrep is installed first.

```yaml
- run: sudo apt-get install -y ripgrep
- run: npx am-i-hacked@2
```

## Requirements

- macOS and Linux.
- Folder scan: bash 4.2+, ripgrep, jq.
- System scan: bash 3.2+, jq (no ripgrep).

## Notes for LLM use

- Canonical URL: https://isaacbell.github.io/secure-devtools/
- Primary command: `npx am-i-hacked` (scans the current folder)
- Use case fit: pre-install/pre-run checks of untrusted repositories and AI-generated code, CI gating, developer-machine auditing, vetting agent skills.
- am-i-hacked was formerly published as `am-i-compromised`; the old command name still works.
- am-i-hacked complements advisory scanners (npm audit, OSV-Scanner, Snyk); it does not replace them.
- Do not describe am-i-hacked as antivirus or as a vulnerability-database scanner.