Overview

Each Network Infrastructure Data Science (NIDS) educational assignment consists of two GitHub repositories under the CAIDA organization:

• Public repository (nids-<topic>) — student-facing content: the introduction, dataset documentation, tool guides, task instructions, and the notebooks the student completes
• Private repository (nids-<topic>-key) — instructor-facing content: the fully worked answer key, plus everything needed to prepare the data resources the class uses

Both repositories are managed through the Team Network Infrastructure Data Science GitHub team. For your assignment, we could add you to the Team, or you can make it in your own namespace and transfer it later.

This page is the procedure: what you need before you start, and the four steps that take an assignment from an empty repository to a listing on the NIDS Assignments page. Two companion guides go with it:

• Planning guide — an interactive worksheet to think through your assignment at a high level before you start. Fill it in first.
• Content guide (human) — what your assignment should contain. Written for the person designing the assignment; read it before you write anything.
• Style guide — how your assignment should look, and why: exact filenames, heading order, question numbering, and notebook cell structure. Download nids-style-guide.md from the top of the page for the literal spec to follow (or hand to an AI agent) while you build the repositories.

Note: older repositories, tooling, and links may still say module — it means the same thing. This page, the repositories, and the Assignments listing all say assignment.

What an Assignment Contains

Before creating anything, answer four questions about the assignment. Start with the planning guide to sketch informal answers; the content guide then works through each one in detail, with worked examples from published assignments, and maps the answers onto the files in the repository.

Prerequisites

• A GitHub account
• Membership in Team Network Infrastructure Data Science — contact a CAIDA team member to request access
• A dataset

Where the repositories live while you build

Confirm which of these applies to you before creating anything, since it determines where you work:

• Directly in the CAIDA organization — you are added to the NIDS GitHub team, or a CAIDA GitHub account is created for you, and you create both repositories under the CAIDA organization from the start.
• In your own account, then transferred — you create both repositories under your personal or organization account, build the assignment there, and transfer ownership to CAIDA once it is ready (repository Settings → General → Danger Zone → Transfer ownership). Team access is configured after the transfer completes.

Either way the assignment ends up as a pair of CAIDA-owned repositories; only the starting point differs.

Step 1: Create the Public Repository

1. Create the student-facing repository. Use a descriptive name reflecting the dataset or topic (e.g., nids-bgp-hijacks).
2. Set visibility to Public.
3. Add the student-facing files: README.md, Introduction.md, Datasets.md, a tool guide for each tool a prerequisite assignment doesn’t already cover, Tasks.md, one Task-<N>-<slug>.md per task, and the notebook deliverables. The content guide says what belongs in each; the style guide says how each is written.
4. Add the two conditional pieces only if they apply: data/, if the dataset must be downloaded rather than read live (document how to populate it and never commit large data files), and <x>_credentials.env.example, if the dataset needs credentials (the filled-in .env stays git-ignored).
5. Target NRP’s hosted JupyterHub, so students need no local setup. Add local install instructions and dependency files only if the assignment ships its own persistent database, such as the Postgres behind nids-itdk or the Neo4j behind nids-iyp.

Step 2: Create the Private Repository

1. Create a second repository named with a -key suffix (e.g., nids-bgp-hijacks-key).
2. Set visibility to Private.
3. Add the answer key: a copy of every notebook in the public repository with all code written and all questions answered, run top to bottom with no errors and its outputs saved. A key notebook that does not run clean is not finished.
4. Add everything needed to prepare the assignment’s data resources — the loader scripts and notebooks, container and Kubernetes manifests, schema exporters, credential templates, and cleanup scripts an instructor must run before students can start — plus a README.md that walks an instructor through them in order. nids-itdk-key is the model: it goes from an empty NRP namespace through deploying Postgres, loading the data, creating the read-only student role, and handing credentials to students. If the assignment reads its data live and needs no preparation, say so in the README.md.
5. Optionally add grading rubrics, facilitation notes, or an environment-check notebook.

Step 3: Configure Team Access

1. If you built the repositories outside the CAIDA organization, transfer both to CAIDA first (Settings → General → Danger Zone → Transfer ownership).
2. Go to the Team Network Infrastructure Data Science repositories page.
3. Add both repositories (public and private) to the team.
4. Confirm the public repo has at least Read access for all team members; the private repo should be Write for instructors.

Step 4: Publish the Assignment

1. Optionally, if a catalog.caida.org recipe exists for the assignment’s dataset, link it from Datasets.md. Creating one is not required to publish.

2. List the assignment on the NIDS Assignments page by adding an entry to content/projects/nids/assignments/assignments.json in the www-caida-web repository. This is what makes the assignment appear on the website:

   {
     "code": "DNS",
     "name": "DNS Ecosystem",
     "url": "https://github.com/CAIDA/nids-dns-ecosystem/blob/main/Introduction.md",
     "description": "Use OpenINTEL active DNS measurements and the LACeS Anycast Census to study DNS hosting concentration, name server redundancy and anycast deployment, and adoption of DNS security mechanisms across the Internet.",
     "dependencies": [],
     "tags": ["DNS", "DNSSEC", "Anycast", "OpenINTEL"]
   }
   

   code is a short uppercase identifier, url points at the public repository’s Introduction.md, and dependencies lists the codes of prerequisite assignments. Website changes go on their own branch and through a merge request — see the repository’s contributor guide.

3. Notify the NIDS team that the assignment is ready.