Getting Started

Getting Started

Get Surfinguard running in 5 minutes. This guide covers both JavaScript/TypeScript and Python.

JavaScript / TypeScript

1. Install the SDK

npm install @surfinguard/sdk

2. Create a Guard Instance

Local mode runs entirely on-device with zero network calls:

import { Guard } from '@surfinguard/sdk';
 
const guard = await Guard.create({ mode: 'local' });

For API mode (cloud-powered with LLM enhancement):

const guard = new Guard({
  mode: 'api',
  apiKey: 'sg_live_your_key_here',
});

3. Check a URL

const result = guard.checkUrl('https://g00gle-login.tk/verify');
 
console.log(result);
// {
//   score: 9,
//   level: "DANGER",
//   primitives: {
//     MANIPULATION: 9,
//     EXFILTRATION: 4,
//     ...
//   },
//   reasons: [
//     "Brand impersonation: google",
//     "Risky TLD: .tk",
//     "Suspicious path: /verify"
//   ],
//   threats: [
//     { id: "U05", name: "Brand impersonation", score: 5, primitive: "MANIPULATION" },
//     { id: "U04", name: "Risky TLD", score: 3, primitive: "MANIPULATION" },
//     ...
//   ]
// }

4. Check a Command

const result = guard.checkCommand('rm -rf / --no-preserve-root');
 
console.log(result.level);   // "DANGER"
console.log(result.score);   // 10
console.log(result.reasons); // ["Destructive command: rm with recursive force and root target"]

5. Use the Result

The level field tells you what to do:

const result = guard.checkUrl(userProvidedUrl);
 
switch (result.level) {
  case 'SAFE':
    // Proceed normally
    await processUrl(userProvidedUrl);
    break;
  case 'CAUTION':
    // Ask for human confirmation
    const approved = await askUser(`Potential risk detected: ${result.reasons.join(', ')}`);
    if (approved) await processUrl(userProvidedUrl);
    break;
  case 'DANGER':
    // Block the action
    throw new Error(`Blocked: ${result.reasons.join(', ')}`);
}

Python

1. Install the SDK

pip install surfinguard

2. Create a Guard Instance

from surfinguard import Guard
 
guard = Guard(api_key="sg_live_your_key_here")

3. Check a URL

result = guard.check_url("https://g00gle-login.tk/verify")
 
print(result.level)    # "DANGER"
print(result.score)    # 9
print(result.reasons)  # ["Brand impersonation: google", "Risky TLD: .tk", ...]

4. Check a Command

result = guard.check_command("rm -rf / --no-preserve-root")
 
print(result.level)    # "DANGER"
print(result.score)    # 10

5. Use the Decorator

The @guard.protect decorator checks the first argument of any function before executing it:

@guard.protect(action_type="url")
def fetch_page(url: str) -> str:
    return requests.get(url).text
 
# This will raise NotAllowedError for dangerous URLs
try:
    fetch_page("https://g00gle-login.tk/verify")
except NotAllowedError as e:
    print(f"Blocked: {e}")

What’s Next

IntroductionRisk Primitives