From 14d1b566d6c1bf31a30f2fbb0308f52d0bfcc29d Mon Sep 17 00:00:00 2001 From: root Date: Tue, 5 May 2026 01:16:27 +0000 Subject: [PATCH] Add safe templates and tooling adoption docs --- AGENTS.md | 4 +++- CLAUDE.md | 5 +++- README.md | 20 ++++++++++++---- Slack Message/.env.example | 12 ++++++++++ accounts.example.json | 10 ++++++++ docs/getting-started.md | 10 ++++++++ docs/repo-map.md | 2 ++ docs/tooling-status.md | 41 +++++++++++++++++++++++++++++++++ github_access_scripts/README.md | 20 +++++----------- scripts/README.md | 24 +++++++++++++++++++ supabase monitor/env.example | 4 ++-- 11 files changed, 130 insertions(+), 22 deletions(-) create mode 100644 Slack Message/.env.example create mode 100644 accounts.example.json create mode 100644 docs/tooling-status.md create mode 100644 scripts/README.md diff --git a/AGENTS.md b/AGENTS.md index cae1fbf..71d1ef3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,7 +17,9 @@ Read these first: 1. `README.md` 2. `docs/getting-started.md` 3. `docs/repo-map.md` -4. `CLAUDE.md` for Claude-specific guidance +4. `docs/tooling-status.md` +5. `scripts/README.md` when the task involves standalone operational scripts +6. `CLAUDE.md` for Claude-specific guidance ## High-Signal Areas diff --git a/CLAUDE.md b/CLAUDE.md index 7873e7c..e4bb4d1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,7 +9,9 @@ Use these as the canonical orientation docs: 1. `README.md` 2. `docs/getting-started.md` 3. `docs/repo-map.md` -4. `AGENTS.md` +4. `docs/tooling-status.md` +5. `scripts/README.md` +6. `AGENTS.md` This file is intentionally short and should not become a second full repo README. @@ -52,4 +54,5 @@ If you change repo structure, onboarding, or navigation, update: - `README.md` - `docs/repo-map.md` +- `docs/tooling-status.md` - `AGENTS.md` if agent navigation is affected diff --git a/README.md b/README.md index 99e473d..37da265 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,10 @@ If you are new to the repo, read these in order: 1. [docs/getting-started.md](docs/getting-started.md) 2. [docs/repo-map.md](docs/repo-map.md) -3. [AGENTS.md](AGENTS.md) if you are working through an AI coding agent -4. [CLAUDE.md](CLAUDE.md) if you are using Claude Code specifically +3. [docs/tooling-status.md](docs/tooling-status.md) +4. [scripts/README.md](scripts/README.md) for supported standalone operational scripts +5. [AGENTS.md](AGENTS.md) if you are working through an AI coding agent +6. [CLAUDE.md](CLAUDE.md) if you are using Claude Code specifically ## Primary Entry Points @@ -68,6 +70,8 @@ These are for scanning many repositories, checking dirty state, and performing s - `docs/` - Canonical onboarding and repo-orientation docs. +- `scripts/README.md` + - Support and usage conventions for standalone operational scripts. - Legacy root docs: - `README_interactive_script.md` - `README_remove_user_script.md` @@ -100,6 +104,14 @@ export GITHUB_TOKEN=your_token_here Use a token with the minimum permissions required for the task. Many admin flows assume `repo` and `admin:org`. +For scripts that require multi-account scanning, start from: + +```bash +cp accounts.example.json accounts.json +``` + +Then fill in real values locally. `accounts.json` is intentionally ignored from future commits. + ## Common Commands ```bash @@ -118,9 +130,9 @@ pre-commit run --all-files - Do not assume every tracked JSON file is a stable source file; many are data snapshots or inputs. - Review scripts before reuse in automation. Some are one-off operational helpers and may encode assumptions about ByteLyst org structure. -## Notes On Tracked Secrets And Outputs +## Notes On Secrets And Outputs -This repo currently contains some tracked local environment files and generated outputs from older workflows. The `.gitignore` now protects against future accidental additions, but tracked files remain tracked until they are intentionally removed from version control in a separate change. +This repo uses example/template files for local credentials and generated outputs should generally stay out of git. If you need local credentials, create untracked local copies such as `accounts.json` or `.env` from the provided examples. ## Contributing diff --git a/Slack Message/.env.example b/Slack Message/.env.example new file mode 100644 index 0000000..2137af2 --- /dev/null +++ b/Slack Message/.env.example @@ -0,0 +1,12 @@ +# Slack Configuration +# Copy this file to .env and replace the placeholder values with your actual tokens + +# Slack Bot/User OAuth Token +# Get this from https://api.slack.com/apps -> Your App -> OAuth & Permissions +# Bot tokens start with 'xoxb-', User tokens start with 'xoxp-' +SLACK_BOT_TOKEN=xoxb-your-bot-token-here + +# Slack Channel ID +# Find this by right-clicking on a channel in Slack -> View channel details +# Channel IDs start with 'C' (public channels), 'D' (direct messages), or 'G' (private channels) +SLACK_CHANNEL_ID=C04ABC123 diff --git a/accounts.example.json b/accounts.example.json new file mode 100644 index 0000000..6f4c094 --- /dev/null +++ b/accounts.example.json @@ -0,0 +1,10 @@ +[ + { + "user": "your_github_username", + "token": "ghp_your_personal_access_token_here" + }, + { + "user": "another_github_username", + "token": "ghp_another_personal_access_token_here" + } +] diff --git a/docs/getting-started.md b/docs/getting-started.md index 5a6dcf0..97b4e0c 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -18,6 +18,10 @@ Start with: - `remove_user_from_repos.sh` - `scripts/ubuntu-vm-security-update.sh` for Ubuntu VM hardening and update automation +For a supported-entry-point overview, also read: + +- `docs/tooling-status.md` + ### If You Need Multi-Repo Git Helpers Start with: @@ -58,6 +62,12 @@ export GITHUB_TOKEN=your_token_here Some workflows also rely on repo-local JSON input files such as `github_repos.json` or `github_acc_input.json`. +If you need multi-account GitHub scanning, create a local file from the template: + +```bash +cp accounts.example.json accounts.json +``` + ## Recommended First Commands ```bash diff --git a/docs/repo-map.md b/docs/repo-map.md index f255cbd..c7cea10 100644 --- a/docs/repo-map.md +++ b/docs/repo-map.md @@ -43,6 +43,7 @@ Current key files: - `docs/getting-started.md` - `docs/repo-map.md` +- `docs/tooling-status.md` - `docs/remove_user_interactive.md` ### `git-work-safety-tools/` @@ -64,6 +65,7 @@ Self-contained operational scripts that do not fit the older root-level naming p Key files: - `ubuntu-vm-security-update.sh` +- `README.md` ### `github_access_scripts/` diff --git a/docs/tooling-status.md b/docs/tooling-status.md new file mode 100644 index 0000000..83beaa9 --- /dev/null +++ b/docs/tooling-status.md @@ -0,0 +1,41 @@ +# Tooling Status + +High-level support map for wider team adoption. + +## Supported Primary Entry Points + +- `bytelyst-cli.sh` +- `remove_user_interactive.sh` +- `remove_user_guided.sh` +- `remove_user_from_repos.sh` +- `git-work-safety-tools/` +- `scripts/ubuntu-vm-security-update.sh` + +These are the main starting points the team should discover first. + +## Specialized But Self-Contained + +- `github_access_scripts/` +- `github_repo_scanners/` +- `Slack Message/` +- `youtube/` +- `supabase monitor/` + +These are useful, but they have narrower scopes or their own setup/runtime assumptions. + +## Legacy Or One-Off Surface Area + +- many root-level `list_*.sh` scripts +- account-specific helper scripts such as `remove_user_i-ayushh18.sh` +- operational snapshot JSON files in the repo root + +These may still be valuable, but they are not the best onboarding path for new teammates. Prefer documenting and linking to the supported entry points above. + +## Team-Readiness Guidance + +Before broad internal rollout: + +- do not keep live credentials in tracked files +- do not keep generated outputs in git unless they are intentional fixtures +- prefer templates such as `accounts.example.json` and `.env.example` +- add new standalone scripts under `scripts/` diff --git a/github_access_scripts/README.md b/github_access_scripts/README.md index 17a90d7..e8495ee 100644 --- a/github_access_scripts/README.md +++ b/github_access_scripts/README.md @@ -4,25 +4,17 @@ This directory contains scripts to check user access to GitHub repositories. ## Setup -1. **Create `accounts.json`:** Before running the scripts, you need to create an `accounts.json` file in the root of this project. This file should contain an array of GitHub accounts, each with a username and a personal access token (PAT). +1. **Create `accounts.json`:** Before running the scripts, create a local `accounts.json` file in the repo root from the provided template: - *Example `accounts.json`:* - ```json - [ - { - "user": "your_github_username", - "token": "your_personal_access_token" - }, - { - "user": "another_github_username", - "token": "another_personal_access_token" - } - ] + ```bash + cp accounts.example.json accounts.json ``` + Then fill it with the GitHub usernames and personal access tokens you want to use for scanning. + 2. **Permissions:** The personal access tokens require the `repo` scope to read repository information and collaborator lists. -> **Security Warning:** Storing personal access tokens in a plaintext file is a security risk. If this file is ever exposed, your accounts could be compromised. For better security, consider using environment variables or a dedicated secrets management tool to handle these credentials. +> **Security Warning:** Storing personal access tokens in a plaintext file is a security risk. Keep `accounts.json` local only and never commit it. The repo now provides `accounts.example.json` as the shareable template. ## Usage diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..1c0df1f --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,24 @@ +# Scripts + +This directory is the preferred home for self-contained operational scripts. + +## Current Scripts + +- `ubuntu-vm-security-update.sh` + - Supported. + - Purpose: update and harden Ubuntu VMs with unattended upgrades, UFW, and fail2ban. + - Risk level: high, because it modifies packages, firewall rules, and reboot behavior. + +## Conventions + +- New standalone operational scripts should go here instead of the repo root. +- Each script should document: + - prerequisites + - required environment variables + - destructive or privileged behavior + - example usage +- Scripts that change host state should support `--help` and a non-destructive preview mode when practical. + +## Legacy Note + +The repo root still contains older shell utilities. Those are not all deprecated, but new work should prefer `scripts/` for clearer ownership and discoverability. diff --git a/supabase monitor/env.example b/supabase monitor/env.example index 9804263..2e89816 100644 --- a/supabase monitor/env.example +++ b/supabase monitor/env.example @@ -1,5 +1,5 @@ # Perplexity API Configuration -PERPLEXITY_API_KEY=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 +PERPLEXITY_API_KEY=your_perplexity_api_key_here # Optional: OpenAI API Key (as backup LLM) -OPENAI_API_KEY=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 +OPENAI_API_KEY=your_openai_api_key_here