Git-Ops Management

Documentation Index

Fetch the complete documentation index at: https://docs.finwatch.finance/llms.txt

Use this file to discover all available pages before exploring further.

​

Why GitOps for Fraud Rules?

• No audit trail. Who changed the rule? When? Why? Most UIs don’t track this well.
• No review process. A single analyst can change a rule that blocks millions of dollars in transactions, with no second pair of eyes.
• No rollback. If a rule change causes false positives, reverting is manual and error-prone.
• No testing. There’s no staging environment, no CI pipeline, no way to test a rule change before it goes live.

​

Setting Up a Rules Repository

​

Creating the Repository

mkdir finwatch-rules
cd finwatch-rules
git init

​

Recommended Directory Structure

finwatch-rules/
├── README.md                    # Overview of your rule set
├── rules/
│   ├── thresholds/
│   │   ├── HighValueCheck.ws
│   │   └── MicroTransactionCheck.ws
│   ├── velocity/
│   │   ├── HighFrequencyDestination.ws
│   │   ├── SourceHighOutflow.ws
│   │   └── RapidSmallBurst.ws
│   ├── compliance/
│   │   ├── SanctionedCountryCheck.ws
│   │   └── SuspiciousDescriptionCheck.ws
│   ├── temporal/
│   │   ├── UnusualTransactionTime.ws
│   │   └── WeekendTransactionCheck.ws
│   └── sequential/
│       └── BlockIfPreviousFailed.ws
└── variables/
    └── lists.json               # External variable definitions

• One rule per .ws file. Always.
• Organize by category. Group rules by the type of fraud pattern they detect.
• Include a README. Document the purpose of each category and any team-specific conventions.
• Store variable definitions alongside rules. This keeps everything in one place.

​

Initial Commit

git add .
git commit -m "Initial rule set: threshold checks and compliance rules"
git remote add origin git@github.com:your-org/finwatch-rules.git
git push -u origin main

​

Connecting FinWatch to Your Repository

​

Configuration

export WATCH_SCRIPT_GIT_REPO="https://github.com/your-org/finwatch-rules.git"
export WATCH_SCRIPT_GIT_BRANCH="main"
export WATCH_SCRIPT_DIR="watch_scripts"

docker run -d \
  --name finwatch \
  -p 8081:8081 \
  -e WATCH_SCRIPT_GIT_REPO="https://github.com/your-org/finwatch-rules.git" \
  -e WATCH_SCRIPT_GIT_BRANCH="main" \
  -e WATCH_SCRIPT_DIR="/app/watch_scripts" \
  finwatch/finwatch:latest

​

What Happens at Startup

1. Validation: Checks that Git is installed on the system. If not, startup fails with a fatal error.
2. Clone or Update: If the local directory doesn’t exist, clones the repository. If it exists but isn’t a valid Git repo, removes it and re-clones. If it’s already a valid repo, pulls the latest changes.
3. Process Existing Scripts: Scans the directory for all .ws files and compiles them into the instruction database.
4. Start Periodic Sync: Begins polling the remote repository for changes every 30 seconds.
5. Start File Watcher: Monitors the local directory for file system changes using fsnotify.

​

The Rule Lifecycle

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  Write   │ →  │  Commit  │ →  │  Pull    │ →  │  Merge   │ →  │  Live    │
│  Rule    │    │  to      │    │  Request │    │  to      │    │  in      │
│  (.ws)   │    │  Branch  │    │  Review  │    │  main    │    │ FinWatch │
└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘

​

Step 1: Write the Rule

git checkout -b rule/high-frequency-destination

cat > rules/velocity/HighFrequencyDestination.ws << 'EOF'
rule HighFrequencyDestination {
    description "Unusually frequent payments to the same destination may require scrutiny."

    when count(when destination == $current.destination, "PT24H") > 10
     and amount > 100

    then review
         score  0.5
         reason "High frequency of transactions to same destination in 24 hours"
}
EOF

​

Step 2: Commit with a Clear Message

git add rules/velocity/HighFrequencyDestination.ws
git commit -m "Add velocity rule: flag >10 transactions to same destination in 24h

- Threshold: 10 transactions per destination per 24 hours
- Minimum amount: $100 (filters out micro-transactions)
- Verdict: review (not block — needs analyst confirmation)
- Score: 0.5 (medium confidence)

Addresses: FRAUD-1234"

• First line: Short summary of what changed.
• Body: Explain the thresholds, the reasoning behind score/verdict choices, and any regulatory context.
• Reference: Link to the fraud investigation ticket or compliance requirement that prompted the rule.

​

Step 3: Open a Pull Request

git push origin rule/high-frequency-destination

• Description: What fraud pattern does this rule detect? Why is it needed?
• Thresholds justification: Why 10 transactions? Why 24 hours? Why $100 minimum?
• Testing evidence: Show test transactions that trigger and don’t trigger the rule.
• Scoring rationale: Why 0.5 and not 0.8?

​

Step 4: Review

• Rule name is descriptive and follows PascalCase convention.
• Description is clear and written for a non-technical audience.
• Conditions are logically correct and cover the intended pattern.
• Cheap conditions are placed before expensive ones (performance).
• Score is appropriate for the confidence level.
• Reason is specific and actionable.
• No typos in field names.
• Time windows are appropriate (not too large, not too small).

​

Step 5: Merge and Auto-Deploy

1. Pulls the latest changes from the repository.
2. Detects the new .ws file.
3. Compiles the rule.
4. Adds it to the active rule set.

​

File Watching

​

Git Polling (Remote Changes)

• Default interval: Every 30 seconds.
• Mechanism: Executes git pull on the tracked branch.
• Behavior: If new commits are found, the updated/new .ws files are automatically recompiled.

​

File System Watching (Local Changes)

• Events monitored: File creation, modification, and deletion.
• File filter: Only .ws files trigger recompilation.
• Behavior: When a .ws file is saved locally, FinWatch recompiles it within seconds.

• In production: The Git polling mechanism picks up merged changes.
• In development: Saving a file locally triggers immediate recompilation, giving you instant feedback.

​

Validation and Error Handling

​

What Happens When a Malformed Rule is Pushed

1. Pull the change.
2. Attempt to compile the rule.
3. Log a parse error with the specific line and column number:
   ERR Failed to compile watch script error="parse error at line 5, column 12: expected verdict (allow, block, review)"
   
4. Skip the malformed rule. Other valid rules continue to function normally.
5. Not crash. A single bad rule does not bring down the engine.

​

Common Parse Errors

​

Pre-Merge Validation

# Validate all .ws files in the rules directory
for file in rules/**/*.ws; do
    finwatch validate "$file"
    if [ $? -ne 0 ]; then
        echo "FAILED: $file"
        exit 1
    fi
done

​

Rolling Back a Rule

​

Revert a Specific Commit

# Find the commit that introduced the problematic rule
git log --oneline rules/velocity/HighFrequencyDestination.ws

# Revert that specific commit
git revert abc1234
git push origin main

​

Revert to a Known-Good State

# Reset the rules directory to a known-good tag
git checkout v1.2.0 -- rules/
git commit -m "Rollback rules to v1.2.0 due to false positive spike"
git push origin main

​

Emergency: Delete a Rule

git rm rules/velocity/HighFrequencyDestination.ws
git commit -m "EMERGENCY: Remove HighFrequencyDestination rule — causing false positives"
git push origin main

​

Team Workflows

​

Branch Naming Convention

rule/<rule-name>          # New rule
fix/<rule-name>           # Fix to an existing rule
tune/<rule-name>          # Score/threshold adjustment
remove/<rule-name>        # Rule removal

​

Required PR Labels

• new-rule — Adding a new rule.
• tune — Adjusting thresholds or scores.
• critical — Changes that affect block verdicts.
• compliance — Changes driven by regulatory requirements.

​

Review Requirements

• Any rule change: At least one peer review from an engineer.
• block verdict rules: Additional review from a compliance officer or fraud analyst.
• Score changes above 0.8: Requires senior engineer approval.
• Variable list updates: Can be approved by the compliance team directly.

​

Tagging Releases

git tag -a v1.3.0 -m "Add velocity detection rules and update sanctions list"
git push origin v1.3.0

​

Triggering a Manual Sync

curl -X POST http://localhost:8081/git/sync

​

Checking Repository Status

curl http://localhost:8081/git/status

​

Next Steps

• Integration Guide — Connect FinWatch to your application’s transaction pipeline.
• Production Deployment — Deploy FinWatch with Git-based rules in a production environment.
• The Rule Cookbook — A library of production-ready rules to seed your repository.
• Troubleshooting — Resolve common Git sync and rule compilation issues.