Skip to content

Develop Contributors Readme Update #84

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
scottbrumley merged 2 commits into from
Nov 24, 2025
Merged

Develop Contributors Readme Update #84

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f9483ee
Rename job and update branch naming validation (#81)
scottbrumley Nov 24, 2025
9e852a2
Add files via upload (#83)
scottbrumley Nov 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 32 additions & 18 deletions .github/workflows/branch-guard.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,31 +1,45 @@
name: Branch name guard
name: Enforce Branch Naming Convention

on:
pull_request:
types: [opened, synchronize, reopened, edited]
types: [opened, edited, synchronize, reopened]

jobs:
validate-branch:
check-branch-name:
runs-on: ubuntu-latest
steps:
- name: Validate SOC Framework branch naming
- name: Get branch name
id: branch
run: |
BRANCH="${{ github.head_ref }}"

TYPE='(feat|fix|chore|docs|refactor)'
# For pull_request events, the source branch is in GITHUB_HEAD_REF
echo "name=${GITHUB_HEAD_REF}" >> "$GITHUB_OUTPUT"

# Added "project" here
MODULE='(entrypoint|upon-trigger|hydration|normalization|enrichment|containment|eradication|recovery|communication|data-modeling|correlation|playbooks|lists|common-utils|dashboards|project)'
- name: Validate branch name against convention
run: |
BRANCH_NAME="${{ steps.branch.outputs.name }}"

COMPONENT='[a-z0-9\-]+'
SLUG='[a-z0-9\-]+'
echo "Branch name: $BRANCH_NAME"

REGEX="^${TYPE}\/${MODULE}\/${COMPONENT}\/${SLUG}$"
# Allowed kinds and areas
REGEX='^(feat|fix|chore|refactor|docs|hotfix)\/(core|endpoint|email|identity|network|pov|tooling)-[a-z0-9-]+$'

if [[ ! "$BRANCH" =~ $REGEX ]]; then
echo "❌ Invalid branch name: $BRANCH"
echo "Expected: <type>/<module>/<component>/<slug>"
echo "Allowed modules include 'project' for workflow/infra updates."
if [[ "$BRANCH_NAME" =~ $REGEX ]]; then
echo "✅ Branch name matches required pattern."
exit 0
else
echo "❌ Invalid branch name: $BRANCH_NAME"
echo ""
echo "Required pattern:"
echo " <kind>/<area>-<short-slug>"
echo ""
echo "Where:"
echo " kind ∈ feat | fix | chore | refactor | docs | hotfix"
echo " area ∈ core | endpoint | email | identity | network | pov | tooling"
echo " slug ∈ lowercase letters, numbers, dashes (e.g. 'normalizer-file-artifacts')"
echo ""
echo "Examples:"
echo " feat/core-normalizer-file-artifacts"
echo " fix/endpoint-containment-timeout-bug"
echo " feat/pov-turla-carbon-scenario"
exit 1
fi

echo "✅ Branch name valid: $BRANCH"
281 changes: 98 additions & 183 deletions Documentation/Contributors.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,225 +1,140 @@
# SOC Optimization Framework — Contributor Guide
# Contributing to the SOC Optimization Framework

This guide explains how to contribute correctly to the SOC Optimization Framework.
It includes the full contribution workflow, branch naming rules, modular coding standards, and PR requirements.
Most contributors will use the **GitHub Web interface**.

Maintainers: @Palo-Cortex/soc-framework-maintainers
You do **not** need Git, the command line, or SDK tools to make basic changes.
This guide explains the simplest way to contribute using the GitHub GUI.
More advanced options are linked at the bottom.

---

# 1. Contribution Workflow

1. Fork the repository
2. Clone your fork:

git clone https://github.com/<your-username>/soc-optimization.git
cd soc-optimization

3. Create a branch using the SOC Framework naming convention
4. Make your changes following the Modular Coding Standards
5. Commit and push your branch
6. Open a Pull Request
7. Tag reviewers: @Palo-Cortex/soc-framework-maintainers
8. Maintainers review → validate → merge
## ⭐ How to Make a Simple Change (GitHub Web GUI)

Use this when you want to update an existing file (playbook, rule, script, modeling rule, installer, documentation, etc.).

1. Open the file you want to change in GitHub
2. Click the **✏️ Edit** button
3. GitHub will prompt you to create a new branch
4. Enter a branch name using this format:
```
<type>/<area>-<short-description>
```
Examples:
```
feat/email-improve-phishing-flow
fix/core-normalizer-hash-bug
docs/core-update-readme
```
5. Click **Create branch and start editing**
6. Make your changes in the editor
7. Scroll down and click **Commit changes**
8. On the next screen, click **Create pull request**
9. In the PR description, briefly describe what you changed
10. Tag the maintainers:
```
@Palo-Cortex/soc-framework-maintainers
```

The maintainers will review your changes and follow up if anything else is needed.

---

# 2. Branch Naming Convention (Required)

Branches also function as feature flags, so correct naming is mandatory.

Format:

<type>/<module>/<component>/<slug>

## Types

feat | fix | chore | docs | refactor

## SOC Framework Modules
## ⭐ How to Upload or Replace a File (From XSIAM → GitHub)

entrypoint
upon-trigger
hydration
normalization
enrichment
containment
eradication
recovery
communication
data-modeling
correlation
playbooks
lists
common-utils
dashboards
project ← for workflows, CI/CD, repo structure, governance
Use this flow when you exported a file from XSIAM and want to update it in the repository.

## Component
1. Navigate to the folder where the file belongs
2. Click **Add file → Upload files**
3. Drag your exported file into the upload area
4. If GitHub shows a message about replacing an existing file with the same name, confirm the replacement
5. In the commit section:
- Make sure **“Commit directly to the `<your-branch-name>` branch”** is selected
- Add a short commit message
- Click **Commit changes**
6. If you haven’t opened a Pull Request yet, click **Compare & pull request**, or use the **Pull requests** tab
7. Describe what you uploaded and why
8. Tag the maintainers

A sub-area within a module. Must be kebab-case.

Examples:

entity-mapping
artifact-extraction
email
endpoint
crowdstrike
case-init
severity
workflows
ci
docs
maintenance

## Slug

Short, clear, kebab-case description of the change.

## Examples

feat/upon-trigger/entity-mapping/auto-resolve-user
fix/data-modeling/crowdstrike/fix-process-lineage
feat/containment/endpoint/auto-isolate-host
docs/playbooks/phishing/update-docs
chore/project/workflows/update-branch-guard
If you're unsure where a file belongs, upload it in the PR and mention it — we will help place it correctly.

---

# 3. Modular Coding Standards (Required)

All contributions must follow the SOC Framework’s modular architecture and FieldOps design principles.

## 3.1 Build “Lego Bricks”

Each contribution must be:
## ⭐ Branch Naming (Required)

- Reusable
- Composable
- Self-contained
- Single-purpose
- Vendor-agnostic unless intentionally vendor-specific
- Free of customer-specific data
Use this pattern:

## 3.2 Place code in the correct SOC Framework layer
```
<type>/<area>-<short-description>
```

Primary architecture:
**Types:**

Entry Point
→ Upon Trigger
→ Hydration
→ Normalization
→ Entity Mapping
→ Artifact Extraction
→ Severity / Priority
→ Ownership
→ Enrichment
→ Containment
→ Eradication
→ Recovery
→ Communication
- `feat` – new feature or behavior
- `fix` – bug fix
- `docs` – documentation changes
- `chore` – maintenance or cleanup
- `refactor` – internal restructuring without changing behavior

Supporting modules:
**Areas:**

Data Modeling
Correlation
Playbooks
Lists
Dashboards
Common Utils
Project (for workflows, CI/CD, governance)
- `core`
- `endpoint`
- `email`
- `identity`
- `network`
- `pov`
- `tooling`

Your contribution must live in the correct directory for the module it supports.
**Examples:**

## 3.3 Vendor Logic Must Be Isolated
```
feat/core-add-file-artifact
fix/endpoint-containment-timeout
docs/email-update-phishing-docs
chore/tooling-update-ci-workflow
```

Examples:

data-modeling/crowdstrike/...
data-modeling/microsoft/...
data-modeling/trendmicro/...

Never mix core logic with vendor-specific code.

## 3.4 Never Include Customer-Specific Data

Do NOT commit:

- Customer usernames
- Domains
- IP addresses
- Tenant identifiers
- Integration instance names

Always use variables, normalized fields, or lists.

## 3.5 Development Sequence: Normalize → Correlate → Playbook

The correct build order:

1. Model your fields
2. Build correlation logic
3. Develop playbooks that consume normalized context

Never build playbooks on raw data.

## 3.6 Documentation Required

Each new module or component must include:

- Purpose
- Inputs
- Outputs
- Dependencies
- Example behavior
More details:
➡️ `docs/BRANCH_NAMING.md`

---

# 4. Pull Request Requirements
## ⭐ What Is a Pull Request? (Short Version)

Every PR must include:
A **Pull Request (PR)** is simply a request to merge your changes into the main project.

## ✔ Proper branch name
When you open a PR:

<type>/<module>/<component>/<slug>
- Maintainners can review your changes
- They can comment and suggest improvements
- When everything looks good, they approve and merge your branch

## ✔ PR checklist completed
- Affected modules selected
- Testing described
- Dependencies listed
- Documentation updated if needed
You do not need to know how Git works behind the scenes.

## ✔ Maintainers tagged
More details:
➡️ `docs/WHAT_IS_A_PR.md`

@Palo-Cortex/soc-framework-maintainers

## ✔ Clean commit messages

Examples:
---

feat(upon-trigger/entity-mapping): improve user identity resolution
fix(data-modeling/crowdstrike): correct process lineage parsing
docs(playbooks/phishing): update flow and explanation
chore(project/workflows): optimize validation workflow
## ⭐ Additional Helpful Guides (Optional)

---
These are **optional** and meant for contributors who want to go deeper:

# 5. Governance Summary
- ➡️ `docs/MULTI_FILE_EDITS.md` – How to edit multiple files in one branch using the GUI
- ➡️ `docs/CONTRIBUTING_ADVANCED.md` – Forking, local development, validation tools
- ➡️ `docs/COMPONENT_DESIGN_GUIDE.md` – How to describe the purpose, inputs, outputs, and test strategy of your component
- ➡️ `docs/WORKFLOW_OVERVIEW.md` – Internal `dev → staging → main` promotion model

- Maintainers team is **visible**, role = **Maintain**
- Admin team is **private**, minimal membership
- All contributors use forks + PRs
- CODEOWNERS enforces mandatory review
- Branch naming validated automatically
- Feature flags generated from branch names
Most contributors can ignore these.

---

# 6. Need Help?
## ⭐ Need Help?

If you get stuck, tag:
If you’re unsure at any point, open a Pull Request and add:

@Palo-Cortex/soc-framework-maintainers
```
@Palo-Cortex/soc-framework-maintainers
```

We’re here to help guide contributors and maintain high standards for the SOC Optimization Framework.
We’re here to help contributors of all experience levels.
Loading