Network permissions (--allow-net) in Deno - Deep Dive

Overview - Network permissions (--allow-net)

What is it?

Network permissions in Deno control which network addresses a program can access. The --allow-net flag lets you specify which websites or IP addresses your Deno script can connect to. Without this permission, your program cannot make any network requests. This helps keep your computer safe by limiting what the code can reach on the internet or local network.

Why it matters

Network permissions exist to protect your computer and data from harmful or unexpected network activity. Without these controls, any Deno script could connect anywhere on the internet, possibly leaking private information or attacking other systems. This permission system makes running code safer, especially when using code from others or the internet.

Where it fits

Before learning about network permissions, you should understand basic Deno commands and how Deno runs scripts. After this, you can learn about other Deno permissions like file system access or environment variables. Later, you might explore how permissions improve security in larger applications or when deploying Deno programs.

Mental Model

Core Idea

Network permissions in Deno act like a gatekeeper that only lets your program talk to approved internet addresses.

Think of it like...

It's like having a guest list at a party: only people on the list can enter and talk to others inside. The --allow-net flag is the list of allowed guests (websites or IPs).

┌─────────────────────────────┐
│        Deno Program          │
└─────────────┬───────────────┘
              │ Requests network access
              ▼
┌─────────────────────────────┐
│   Network Permission Gate    │
│  (controlled by --allow-net)│
└─────────────┬───────────────┘
              │ Allows only approved addresses
              ▼
┌─────────────────────────────┐
│       Internet / Network     │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

What is --allow-net Permission

Concept: Introduces the basic idea of the --allow-net flag in Deno.

Deno is secure by default, meaning it blocks network access unless you explicitly allow it. The --allow-net flag lets your program connect to the internet or local network. You can allow all network access by just using --allow-net or restrict it to specific domains or IPs by adding them after the flag, like --allow-net=example.com.

Result

Your Deno program can make network requests only to the addresses you allowed or nowhere if you don't use --allow-net.

Understanding that Deno blocks network access by default helps you see why --allow-net is necessary to enable network features safely.

2

Foundation

Default Network Access Behavior

Concept: Explains what happens if you run a network request without --allow-net.

If you try to fetch data from the internet in Deno without --allow-net, the program will stop and show an error about missing network permission. This prevents accidental or malicious network calls.

Result

Network requests fail with a permission error unless --allow-net is used.

Knowing the default block prevents confusion when network code doesn't work and highlights Deno's security-first design.

3

Intermediate

Allowing Specific Domains Only

🤔Before reading on: do you think --allow-net=example.com allows connections to sub.example.com? Commit to your answer.

Concept: Shows how to restrict network access to certain domains or IPs.

You can limit network access by listing domains or IPs after --allow-net, separated by commas. For example, --allow-net=example.com,api.example.com lets your program connect only to those two addresses. This is safer than allowing all network access.

Result

Your program can only connect to the specified domains or IPs, blocking all others.

Restricting network access reduces risk by limiting where your program can send or receive data.

4

Intermediate

Allowing Network Access for Tests

🤔Before reading on: should tests always have full network access? Commit to your answer.

Concept: Discusses how to handle network permissions when running tests in Deno.

When running tests that need network access, you must use --allow-net. You can allow all or specific domains. For example, deno test --allow-net=localhost lets tests connect to local servers. This keeps tests secure and controlled.

Result

Tests that require network calls run successfully with proper permissions.

Knowing how to grant network access in tests helps maintain security while allowing necessary functionality.

5

Advanced

Combining --allow-net with Other Permissions

🤔Before reading on: do you think --allow-net alone is enough for all network-related tasks? Commit to your answer.

Concept: Explains how --allow-net works with other Deno permissions like --allow-read or --allow-env.

Network access often needs to be combined with other permissions. For example, fetching a URL and saving the result requires --allow-net and --allow-write. Understanding how these permissions interact helps you grant only what is necessary.

Result

Programs run with minimal permissions needed for their tasks, improving security.

Knowing permission combinations prevents over-permissioning and reduces attack surface.

6

Advanced

Security Risks Without Proper Network Restrictions

🤔Before reading on: do you think allowing all network access is always safe? Commit to your answer.

Concept: Highlights dangers of granting broad network permissions.

Allowing all network access (--allow-net without restrictions) can let malicious code send data anywhere or attack other systems. Restricting domains limits damage if code is compromised or buggy.

Result

Better security posture by minimizing network exposure.

Understanding risks encourages careful permission granting and safer code execution.

7

Expert

Internal Permission Checks and Runtime Enforcement

🤔Before reading on: do you think Deno checks network permissions before or after making a connection? Commit to your answer.

Concept: Describes how Deno enforces network permissions at runtime.

Deno intercepts network calls at runtime and checks if the requested address matches allowed patterns. If not allowed, it throws a permission error before any data is sent or received. This enforcement is built into Deno's core runtime for security.

Result

Network calls are blocked immediately if not permitted, preventing unauthorized access.

Knowing runtime enforcement clarifies why permissions cannot be bypassed and how Deno maintains security.

Under the Hood

Deno's runtime includes a permission system that intercepts system calls for network access. When a program tries to open a network connection, Deno checks the requested address against the allowed list from --allow-net. This check happens before the connection is established. If the address is not allowed, Deno throws a runtime error and stops the connection attempt. This mechanism uses pattern matching for domains and IPs, supporting wildcards and multiple entries.

Why designed this way?

Deno was designed to be secure by default to prevent accidental or malicious harm from running untrusted code. The permission system, including --allow-net, was created to give developers fine control over what their programs can do. Alternatives like no permissions or all-permissions-by-default were rejected because they expose users to security risks. This design balances usability and safety, encouraging explicit permission granting.

┌─────────────────────────────┐
│       Deno Runtime          │
│  (Permission System Layer)  │
└─────────────┬───────────────┘
              │ Intercepts network calls
              ▼
┌─────────────────────────────┐
│  Check requested address     │
│  against --allow-net list    │
└───────┬───────────────┬─────┘
        │               │
        │ Allowed       │ Not Allowed
        ▼               ▼
┌───────────────┐  ┌───────────────┐
│ Establish     │  │ Throw runtime  │
│ network conn. │  │ permission err │
└───────────────┘  └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does --allow-net=example.com allow connections to sub.example.com? Commit to yes or no.

Common Belief: Many believe --allow-net=example.com automatically allows all subdomains like sub.example.com.

Reality: The flag only allows the exact domain specified. Subdomains must be explicitly listed or allowed with wildcards.

Why it matters: Assuming subdomains are allowed can lead to unexpected permission errors or security holes if subdomains are not intended to be accessible.

Quick: If you run Deno with --allow-net, does it mean your program can access any network address? Commit to yes or no.

Common Belief: Some think --allow-net without arguments means no restrictions at all.

Reality: Using --allow-net alone grants full network access to all addresses, which can be risky.

Why it matters: Over-permissioning can expose your system to attacks or data leaks if the code is compromised.

Quick: Does --allow-net control outgoing and incoming network connections? Commit to yes or no.

Common Belief: People often believe --allow-net controls both outgoing and incoming network traffic.

Reality: --allow-net only controls outgoing network requests initiated by the program, not incoming connections like servers listening on ports.

Why it matters: Misunderstanding this can cause confusion when setting up servers or expecting permission errors on incoming connections.

Quick: Can you bypass --allow-net restrictions by using other permissions like --allow-read? Commit to yes or no.

Common Belief: Some think other permissions can override or bypass network restrictions.

Reality: Network permissions are enforced independently and cannot be bypassed by other permissions.

Why it matters: Believing this can lead to false assumptions about security and accidental exposure.

Expert Zone

1

The --allow-net flag supports wildcards like --allow-net=*.example.com, but this only matches subdomains, not the root domain itself.

2

Deno's permission checks happen synchronously before the network call, which means permission errors are immediate and prevent any partial network activity.

3

When multiple --allow-net flags are used, Deno merges them, allowing combined access lists, but order and specificity can affect which addresses are permitted.

When NOT to use

Avoid using --allow-net without restrictions in production or untrusted code. Instead, specify exact domains or IPs. For local development, consider using --allow-net=localhost. If your program needs to act as a server accepting incoming connections, use --allow-net along with --allow-run or other relevant flags, but understand incoming connections are not controlled by --allow-net alone.

Production Patterns

In production, developers often restrict --allow-net to only the APIs or services their application needs, minimizing exposure. For example, a web scraper might allow only the target website's domain. CI/CD pipelines run tests with minimal network permissions, often only localhost. Some projects use environment variables or config files to dynamically set allowed domains, improving flexibility and security.

Connections

Sandboxing in Operating Systems

Both limit what programs can do to protect the system.

Understanding OS sandboxing helps grasp why Deno restricts network access to prevent harmful actions.

Firewall Rules

Both control network access but at different layers—Deno at program level, firewall at system/network level.

Knowing firewall concepts clarifies how Deno's permission system complements broader network security.

Access Control Lists (ACLs) in Security

Deno's --allow-net acts like an ACL specifying allowed network addresses.

Recognizing this pattern helps understand permission systems across computing and security domains.

Common Pitfalls

#1 Granting full network access without restrictions.

Wrong approach:

deno run --allow-net script.ts

Correct approach:

deno run --allow-net=example.com,api.example.com script.ts

Root cause:

Misunderstanding that --allow-net without arguments means unrestricted access, which increases security risks.

#2 Expecting subdomains to be allowed automatically.

Wrong approach:

deno run --allow-net=example.com script.ts // tries to access sub.example.com

Correct approach:

deno run --allow-net=example.com,sub.example.com script.ts

Root cause:

Assuming domain permissions include subdomains without explicit listing or wildcards.

#3 Trying to bypass network restrictions using other permissions.

Wrong approach:

deno run --allow-read script.ts // expects network access without --allow-net

Correct approach:

deno run --allow-net script.ts

Root cause:

Confusing different permission types and thinking one can override another.

Key Takeaways

Deno blocks network access by default to keep your system safe.

The --allow-net flag explicitly grants permission to connect to specified network addresses.

Restricting network access to specific domains reduces security risks.

Network permissions are enforced at runtime before any connection is made.

Misunderstanding domain restrictions or permission scopes can cause errors or security issues.

Practice

1. What does the --allow-net flag do when running a Deno program?

easy

A. It allows the program to access the network.

B. It disables all network access for the program.

C. It grants permission to read local files.

D. It enables debugging mode for the program.

Solution

1. Step 1: Understand the purpose of --allow-net

   This flag is used to grant network access to a Deno program, which is otherwise restricted for security.

2. Step 2: Compare options with the flag's function

   Only "It allows the program to access the network." correctly states that --allow-net allows network access. Other options describe unrelated permissions or features.

3. Final Answer:

   It allows the program to access the network. -> Option A

4. Quick Check:

   Network permission = Allow network access [OK]

Hint: Remember: --allow-net means allow network access [OK]

Common Mistakes:

• Confusing --allow-net with file permissions
• Thinking it disables network access
• Mixing it up with debugging flags

2. Which of the following is the correct way to allow network access only to example.com when running a Deno script named app.ts?

easy

A. deno run app.ts --allow-net=example.com

B. deno run --allow-net app.ts example.com

C. deno run --allow-net=example.com app.ts

D. deno run --allow-net example.com app.ts

Solution

1. Step 1: Identify correct flag syntax for domain restriction

   The correct syntax is --allow-net=domain placed before the script name.

2. Step 2: Check command order and placement

   deno run --allow-net=example.com app.ts correctly places --allow-net=example.com before app.ts. Other options have incorrect order or syntax.

3. Final Answer:

   deno run --allow-net=example.com app.ts -> Option C

4. Quick Check:

   Correct flag syntax = deno run --allow-net=example.com app.ts [OK]

Hint: Put --allow-net=domain before script name [OK]

Common Mistakes:

• Placing domain after script name
• Using space instead of '=' between flag and domain
• Putting script name before flags

3. Consider this Deno command and script:

deno run --allow-net=deno.land app.ts

And app.ts contains:

const response = await fetch('https://deno.land/std/http/file_server.ts');
console.log(response.status);

What will be the output?

medium

A. SyntaxError

B. PermissionDenied: network access to "deno.land" is not allowed

C. 404

D. 200

Solution

1. Step 1: Check network permission for the domain

   The command allows network access only to "deno.land", which matches the fetch URL domain.

2. Step 2: Understand fetch behavior with permission

   Since permission is granted, fetch succeeds and returns HTTP status 200 for a valid resource.

3. Final Answer:

   200 -> Option D

4. Quick Check:

   Allowed domain fetch = 200 status [OK]

Hint: Allowed domain fetch returns 200 status [OK]

Common Mistakes:

• Assuming permission error despite allowed domain
• Confusing 404 with permission issues
• Expecting syntax errors from fetch

4. You run this command:

deno run --allow-net=example.com app.ts

Inside app.ts you fetch https://google.com. What error will you get?

medium

A. PermissionDenied: network access to "google.com" is not allowed

B. No error, fetch succeeds

C. TypeError: Invalid URL

D. ReferenceError: fetch is not defined

Solution

1. Step 1: Analyze allowed domains

   The command only allows network access to "example.com" but the script tries to fetch "google.com".

2. Step 2: Understand Deno's permission enforcement

   Deno blocks network requests to domains not allowed, causing a PermissionDenied error.

3. Final Answer:

   PermissionDenied: network access to "google.com" is not allowed -> Option A

4. Quick Check:

   Disallowed domain fetch = PermissionDenied error [OK]

Hint: Fetch outside allowed domain causes PermissionDenied [OK]

Common Mistakes:

• Thinking fetch will succeed without permission
• Confusing permission error with URL or reference errors
• Ignoring domain restrictions in --allow-net

5. You want to run a Deno script that fetches data from both api.example.com and data.service.org. Which command correctly grants network access to both domains using a single --allow-net flag?

hard

A. deno run --allow-net=api.example.com --allow-net=data.service.org app.ts

B. deno run --allow-net=api.example.com,data.service.org app.ts

C. deno run --allow-net app.ts api.example.com data.service.org

D. deno run --allow-net=api.example.com;data.service.org app.ts

Solution

1. Step 1: Understand multiple domain syntax for --allow-net

   Deno accepts multiple domains separated by commas in a single --allow-net flag.

2. Step 2: Evaluate each option's correctness

   deno run --allow-net=api.example.com,data.service.org app.ts uses comma-separated domains correctly. deno run --allow-net=api.example.com --allow-net=data.service.org app.ts repeats the flag (not a single flag). deno run --allow-net app.ts api.example.com data.service.org misplaces domains as arguments. deno run --allow-net=api.example.com;data.service.org app.ts uses semicolon which is incorrect.

3. Final Answer:

   deno run --allow-net=api.example.com,data.service.org app.ts -> Option B

4. Quick Check:

   Multiple domains = comma-separated in one flag [OK]

Hint: Use commas to list multiple domains in --allow-net [OK]

Common Mistakes:

• Using multiple --allow-net flags
• Separating domains with semicolons
• Placing domains after script name