Merge pull request #2150 from guardicore/2105-add-docstrings

Add docstrings to auth endpoints

monkey/monkey_island/cc/app.py

@@ -22,7 +22,7 @@ from monkey_island.cc.resources.agent_configuration import AgentConfiguration
 from monkey_island.cc.resources.agent_controls import StopAgentCheck, StopAllAgents
 from monkey_island.cc.resources.attack.attack_report import AttackReport
 from monkey_island.cc.resources.auth.authenticate import Authenticate, init_jwt
-from monkey_island.cc.resources.auth.register import Registration
+from monkey_island.cc.resources.auth.register import Register
 from monkey_island.cc.resources.auth.registration_status import RegistrationStatus
 from monkey_island.cc.resources.blackbox.log_blackbox_endpoint import LogBlackboxEndpoint
 from monkey_island.cc.resources.blackbox.monkey_blackbox_endpoint import MonkeyBlackboxEndpoint
@@ -153,7 +153,7 @@ def init_api_resources(api: FlaskDIWrapper):
 
 def init_restful_endpoints(api: FlaskDIWrapper):
     api.add_resource(Root)
-    api.add_resource(Registration)
+    api.add_resource(Register)
     api.add_resource(RegistrationStatus)
     api.add_resource(Authenticate)
     api.add_resource(Monkey)

monkey/monkey_island/cc/resources/auth/authenticate.py

@@ -22,10 +22,7 @@ def init_jwt(app):
 
 class Authenticate(AbstractResource):
     """
-    Resource for user authentication. The user provides the username and password and we \
-    give them a JWT. \
-    See `AuthService.js` file for the frontend counterpart for this code. \
-
+    A resource for user authentication
     """
 
     urls = ["/api/authenticate"]
@@ -35,13 +32,15 @@ class Authenticate(AbstractResource):
 
     def post(self):
         """
-        Example request: \
-        { \
-            "username": "my_user", \
-            "password": "my_password" \
-        } \
+        Authenticates a user
 
+        Gets a username and password from the request sent from the client, authenticates, and
+        returns an access token
+
+        :return: Access token in the response body
+        :raises IncorrectCredentialsError: If credentials are invalid
         """
+
         username, password = get_username_password_from_request(request)
 
         try:

monkey/monkey_island/cc/resources/auth/register.py

@@ -11,7 +11,10 @@ from monkey_island.cc.services import AuthenticationService
 logger = logging.getLogger(__name__)
 
 
-class Registration(AbstractResource):
+class Register(AbstractResource):
+    """
+    A resource for user registration
+    """
 
     urls = ["/api/register"]
 
@@ -19,6 +22,16 @@ class Registration(AbstractResource):
         self._authentication_service = authentication_service
 
     def post(self):
+        """
+        Registers a new user
+
+        Gets a username and password from the request sent from the client,
+        and registers a new user
+
+        :raises InvalidRegistrationCredentialsError: If username or password is empty
+        :raises AlreadyRegisteredError: If a user has already been registered
+        """
+
         username, password = get_username_password_from_request(request)
 
         try:

monkey/monkey_island/cc/services/authentication_service.py

@@ -18,6 +18,10 @@ from monkey_island.cc.setup.mongo.database_initializer import reset_database
 
 
 class AuthenticationService:
+    """
+    A service for user authentication
+    """
+
     def __init__(
         self,
         data_dir: Path,
@@ -29,9 +33,21 @@ class AuthenticationService:
         self._repository_encryptor = repository_encryptor
 
     def needs_registration(self) -> bool:
+        """
+        Checks if a user is already registered on the Island
+
+        :return: Whether registration is required on the Island
+        """
         return not self._user_repository.has_registered_users()
 
     def register_new_user(self, username: str, password: str):
+        """
+        Registers a new user on the Island, then resets the encryptor and database
+
+        :param username: Username to register
+        :param password: Password to register
+        :raises InvalidRegistrationCredentialsError: If username or password is empty
+        """
         if not username or not password:
             raise InvalidRegistrationCredentialsError("Username or password can not be empty.")
 

monkey/tests/unit_tests/monkey_island/cc/resources/auth/test_register.py

@@ -4,9 +4,9 @@ from unittest.mock import MagicMock
 import pytest
 
 from common.utils.exceptions import AlreadyRegisteredError, InvalidRegistrationCredentialsError
-from monkey_island.cc.resources.auth.register import Registration
+from monkey_island.cc.resources.auth.register import Register
 
-REGISTRATION_URL = Registration.urls[0]
+REGISTRATION_URL = Register.urls[0]
 
 USERNAME = "test_user"
 PASSWORD = "test_password"